inbox-mcp 1.0.0

Provider-agnostic email MCP server for AI assistants

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="[e-mail]"
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:

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": "[e-mail]",
        "INBOX_MCP_PASSWORD": "your-app-password"
      }
    }
  }
}

Claude Code

claude mcp add -e INBOX_MCP_EMAIL=[e-mail] -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": "[e-mail]",
        "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": "[e-mail]",
        "INBOX_MCP_PASSWORD": "work-password",
        "INBOX_MCP_HOST": "mail.company.com"
      }
    },
    "personal-email": {
      "command": "inbox-mcp",
      "env": {
        "INBOX_MCP_EMAIL": "[e-mail]",
        "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 [e-mail] for a commercial license.