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

pip install inbox-mcp

Configuration

Set two environment variables:

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

All Environment Variables

Provider Auto-Detection

Gmail Setup

Gmail requires an App Password:

1. Enable 2-Step Verification on your Google account

2. Go to App Passwords

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):

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

Claude Code

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:

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

Running Directly

# As entry point
inbox-mcp

# As module
python -m inbox_mcp

Tools

Write tools are disabled when INBOX_MCP_READ_ONLY=true.

Multiple Accounts

Run multiple instances with different names:

{
  "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)

• Commercial — for proprietary use (see 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.