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

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
yahoo.com, ymail.com, rocketmail.com	yahoo	imap.mail.yahoo.com
anything else	generic	imap.{domain}

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

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:

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

<!-- mcp-name: io.github.p-w-4-z/inbox-mcp -->