imap-mcp

An MCP (Model Context Protocol) server for IMAP/SMTP email. Lets AI agents like Claude Code read, send, search, and manage email via standard IMAP and SMTP — works with any email provider (Gmail, Outlook/Exchange, Fastmail, self-hosted, etc.).

Tools

Tool	Description
imap_list_accounts	List all configured accounts
imap_list_folders	List all IMAP folders/mailboxes
imap_list_messages	List recent messages in a folder; returns total_unread count when unread_only=true
imap_read_message	Read the full body of a message by UID
imap_search_messages	Search messages by keyword with pagination (count up to 500, offset)
imap_send_email	Send a new email via SMTP
imap_reply	Reply to a message (preserves threading headers)
imap_forward	Forward a message to new recipients
imap_mark_read	Mark a single message as read or unread
imap_mark_read_bulk	Mark multiple messages as read or unread in one operation
imap_move_message	Move a message to another folder
imap_delete_message	Delete or trash a single message
imap_delete_messages	Delete or trash multiple messages in one operation

Setup

1. Install and build

git clone https://github.com/prixite/imap-mcp
cd imap-mcp
npm install
npm run build

2. Configure accounts

Copy the example config and edit it:

cp accounts.example.json ~/.imap-mcp.json
# Edit ~/.imap-mcp.json with your account details

The config file location defaults to ~/.imap-mcp.json. Override with the IMAP_MCP_CONFIG environment variable.

For Gmail: Enable 2-Step Verification and create an App Password. Use the 16-character app password in the config.

For Outlook/Microsoft 365: Enable IMAP in account settings and use an app password (if MFA is enabled).

3. Register with Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "imap": {
      "command": "node",
      "args": ["/path/to/imap-mcp/dist/index.js"]
    }
  }
}

Then restart Claude Code.

Config format

{
  "accounts": [
    {
      "name": "Work",
      "email": "you@company.com",
      "imap": {
        "host": "imap.company.com",
        "port": 993,
        "secure": true,
        "auth": { "user": "you@company.com", "pass": "app-password" }
      },
      "smtp": {
        "host": "smtp.company.com",
        "port": 587,
        "secure": false,
        "auth": { "user": "you@company.com", "pass": "app-password" }
      }
    }
  ]
}

• secure: true — TLS from the start (IMAP port 993, SMTP port 465)
• secure: false — STARTTLS (IMAP port 143, SMTP port 587)

License

MIT