Skip to main content
Glama
TheGoldfingerCH

mcp-imap

by TheGoldfingerCH
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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.

Related MCP server: mcp-email-client

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-email

    OneShotForge
    F
    license
    Not graded
    quality
    D
    maintenance
    Self-hosted MCP server for any IMAP/SMTP inbox. Multi-account in one config. Built for Claude Code.
    -

  • mcp-email-client

    gamalan
    F
    license
    C
    quality
    D
    maintenance
    A Python-based MCP server for managing email configurations, sending emails, and reading the latest unread emails.
    12
    18
    -

  • email-mcp-server

    0xshariq
    A
    license
    Not graded
    quality
    C
    maintenance
    Cross-platform MCP server and CLI for email operations, including send, read, search, and contact management, compatible with Gmail, Outlook, Yahoo, and any IMAP/SMTP providers.
    8 npm
    1
    MIT

  • email-mcp

    swapnilsurdi
    A
    license
    A
    quality
    D
    maintenance
    Local MCP server for multi-account IMAP/SMTP email (iCloud + Gmail via app-specific passwords). Never marks mail read. Cross-folder search, idempotent sends, TLS verified.
    8
    MIT