Metadata-Version: 2.4
Name: inbox-mcp
Version: 1.0.0
Summary: Provider-agnostic email MCP server for AI assistants
Project-URL: Homepage, https://github.com/p-w-4-z/inbox-mcp
Project-URL: Repository, https://github.com/p-w-4-z/inbox-mcp
Project-URL: Issues, https://github.com/p-w-4-z/inbox-mcp/issues
Author-email: breact <hello@breact.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
License-File: LICENSE-COMMERCIAL
Keywords: ai,assistant,claude,email,imap,llm,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# inbox-mcp

Provider-agnostic email MCP server for AI assistants. Connect any IMAP mailbox to Claude Desktop, Cursor, VS Code, or any MCP-compatible client.

## Features

- **8 email tools**: get_summary, list_messages, read_message, search, list_folders, mark_read, move_message, create_folder
- **Provider auto-detection**: Automatically configures Gmail, Outlook, GMX from your email address
- **Any IMAP server**: Works with any standard IMAP provider out of the box
- **Read-only mode**: Optional safety mode that disables all write operations
- **Security-first**: No delete operations exposed. Ever.

## Quick Start

```bash
pip install inbox-mcp
```

## Configuration

Set two environment variables:

```bash
export INBOX_MCP_EMAIL="you@gmail.com"
export INBOX_MCP_PASSWORD="your-app-password"
```

### All Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `INBOX_MCP_EMAIL` | Yes | — | Your email address |
| `INBOX_MCP_PASSWORD` | Yes | — | Password or app password |
| `INBOX_MCP_HOST` | No | Auto-detected | IMAP server hostname |
| `INBOX_MCP_PORT` | No | 993 | IMAP port |
| `INBOX_MCP_PROVIDER` | No | Auto-detected | Force provider: gmail, outlook, gmx, generic |
| `INBOX_MCP_READ_ONLY` | No | false | Set to `true` to disable write operations |

### Provider Auto-Detection

| Email Domain | Provider | IMAP Host |
|-------------|----------|-----------|
| gmail.com, googlemail.com | gmail | imap.gmail.com |
| outlook.com, hotmail.com, live.com | outlook | outlook.office365.com |
| gmx.net, gmx.at, gmx.de, gmx.ch, gmx.com | gmx | imap.gmx.net |
| anything else | generic | imap.{domain} |

### Gmail Setup

Gmail requires an [App Password](https://support.google.com/accounts/answer/185833):

1. Enable 2-Step Verification on your Google account
2. Go to [App Passwords](https://myaccount.google.com/apppasswords)
3. Generate a password for "Mail"
4. Use that as `INBOX_MCP_PASSWORD`

## Client Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "inbox": {
      "command": "inbox-mcp",
      "env": {
        "INBOX_MCP_EMAIL": "you@gmail.com",
        "INBOX_MCP_PASSWORD": "your-app-password"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add -e INBOX_MCP_EMAIL=you@gmail.com -e INBOX_MCP_PASSWORD=your-app-password inbox inbox-mcp
```

### Cursor / VS Code

Add to `.cursor/mcp.json` or `.vscode/mcp.json`:

```json
{
  "mcpServers": {
    "inbox": {
      "command": "inbox-mcp",
      "env": {
        "INBOX_MCP_EMAIL": "you@gmail.com",
        "INBOX_MCP_PASSWORD": "your-app-password"
      }
    }
  }
}
```

### Running Directly

```bash
# As entry point
inbox-mcp

# As module
python -m inbox_mcp
```

## Tools

| Tool | Description | Write? |
|------|-------------|--------|
| `get_summary` | Inbox stats: total, unread, last 7 days | No |
| `list_messages` | List messages with filters (all, unread, today, week) | No |
| `read_message` | Full message body by sequence number | No |
| `search` | Search by subject or sender | No |
| `list_folders` | List all IMAP folders/labels | No |
| `mark_read` | Set messages as read | Yes |
| `move_message` | Move messages between folders | Yes |
| `create_folder` | Create a new IMAP folder | Yes |

Write tools are disabled when `INBOX_MCP_READ_ONLY=true`.

## Multiple Accounts

Run multiple instances with different names:

```json
{
  "mcpServers": {
    "work-email": {
      "command": "inbox-mcp",
      "env": {
        "INBOX_MCP_EMAIL": "you@company.com",
        "INBOX_MCP_PASSWORD": "work-password",
        "INBOX_MCP_HOST": "mail.company.com"
      }
    },
    "personal-email": {
      "command": "inbox-mcp",
      "env": {
        "INBOX_MCP_EMAIL": "you@gmail.com",
        "INBOX_MCP_PASSWORD": "gmail-app-password"
      }
    }
  }
}
```

## License

Dual-licensed:

- **AGPL-3.0** — free for open-source use (see [LICENSE](LICENSE))
- **Commercial** — for proprietary use (see [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL))

If your project is open-source, you can use inbox-mcp under AGPL-3.0 at no cost. For proprietary/closed-source use, contact hello@breact.com for a commercial license.
