mcp-imap

A minimal MCP server for reading and sending emails via IMAP/SMTP — works with any mail provider (Infomaniak, Gmail, iCloud, Proton Bridge, etc.) and supports multiple accounts in a single instance.

Zero external dependencies — uses Python's built-in imaplib, smtplib and email modules only.

Compatible with Hermes, Claude Desktop, Cursor, and any MCP-compatible client.

Tools

Tool	Description
list_accounts	List all configured mail accounts
list_folders	List available IMAP folders
list_emails	List recent emails (with unread filter)
read_email	Read full email content by UID
search_emails	Search emails by keyword (subject or sender)
send_email	Send an email via SMTP
move_email	Move email to another folder
mark_as_read	Mark email as read

All tools accept an optional account parameter to target a specific account (e.g. "pro", "perso"). Omit it to use the default account.

Installation

git clone https://github.com/TheGoldfingerCH/mcp-imap
cd mcp-imap
cp .env.example .env
# Edit .env with your credentials

Python 3.12+ required. No pip install needed.

Multi-account setup

Add as many accounts as you need using the MAIL_<ACCOUNT>_* pattern in .env:

# Default account
MAIL_USER=you@yourdomain.com
MAIL_PASS=password
MAIL_IMAP_HOST=imap.example.com
MAIL_SMTP_HOST=smtp.example.com

# Second account named "pro"
MAIL_PRO_USER=pro@company.com
MAIL_PRO_PASS=password
MAIL_PRO_IMAP_HOST=imap.company.com
MAIL_PRO_SMTP_HOST=smtp.company.com

# Third account named "perso"
MAIL_PERSO_USER=me@gmail.com
MAIL_PERSO_PASS=app_password
MAIL_PERSO_IMAP_HOST=imap.gmail.com
MAIL_PERSO_SMTP_HOST=smtp.gmail.com

Then in the AI chat:

• list_emails() → default account inbox
• list_emails(account="pro") → pro account inbox
• send_email(to="...", subject="...", body="...", account="perso") → send from perso account

Configuration

Edit .env:

MAIL_IMAP_HOST=imap.yourprovider.com
MAIL_IMAP_PORT=993

MAIL_SMTP_HOST=smtp.yourprovider.com
MAIL_SMTP_PORT=587

MAIL_USER=you@yourdomain.com
MAIL_PASS=your_password
MAIL_FROM=you@yourdomain.com

Hermes

Add to ~/.hermes/config.yaml (or ~/.hermes-prive/config.yaml for a private instance):

mcp_servers:
  - name: imap
    command: python
    args:
      - /path/to/mcp-imap/src/cli.py
    env:
      MAIL_IMAP_HOST: imap.yourprovider.com
      MAIL_IMAP_PORT: "993"
      MAIL_SMTP_HOST: smtp.yourprovider.com
      MAIL_SMTP_PORT: "587"
      MAIL_USER: you@yourdomain.com
      MAIL_PASS: your_password
      MAIL_FROM: you@yourdomain.com

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "imap": {
      "command": "python",
      "args": ["/path/to/mcp-imap/src/cli.py"],
      "env": {
        "MAIL_IMAP_HOST": "imap.yourprovider.com",
        "MAIL_IMAP_PORT": "993",
        "MAIL_SMTP_HOST": "smtp.yourprovider.com",
        "MAIL_SMTP_PORT": "587",
        "MAIL_USER": "you@yourdomain.com",
        "MAIL_PASS": "your_password",
        "MAIL_FROM": "you@yourdomain.com"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "imap": {
      "command": "python",
      "args": ["/path/to/mcp-imap/src/cli.py"],
      "env": {
        "MAIL_IMAP_HOST": "imap.yourprovider.com",
        "MAIL_IMAP_PORT": "993",
        "MAIL_SMTP_HOST": "smtp.yourprovider.com",
        "MAIL_SMTP_PORT": "587",
        "MAIL_USER": "you@yourdomain.com",
        "MAIL_PASS": "your_password",
        "MAIL_FROM": "you@yourdomain.com"
      }
    }
  }
}

Security

• Credentials are read from environment variables or .env — never hardcoded
• .env is in .gitignore — never commit it
• Only imaplib, smtplib, email (Python stdlib) — no supply chain risk
• Email body is truncated at 4000 chars to protect context window

Provider examples

Provider	IMAP host	SMTP host	SMTP port
Infomaniak	mail.infomaniak.com	mail.infomaniak.com	587
Gmail	imap.gmail.com	smtp.gmail.com	587
iCloud	imap.mail.me.com	smtp.mail.me.com	587
Proton Bridge	127.0.0.1	127.0.0.1	1025

License

MIT — © TheGoldfinch