Back to MCP Servers

Email

IMAP/SMTP email MCP server with 42 tools for reading, searching, sending, scheduling, and managing emails across multiple accounts. Supports IMAP IDLE push, AI triage, desktop notifications, and auto-detects providers like Gmail, Outlook, and iCloud.

communicationai
By codefuturist
6534Updated 1 month agoTypeScriptLGPL-3.0

Installation

npx -y email-mcp

Configuration

{
  "mcpServers": {
    "email-mcp": {
      "command": "npx",
      "args": ["-y", "email-mcp"]
    }
  }
}

How to use

  1. Run the installation command above (if needed)
  2. Open your Claude Code settings file (~/.claude/settings.json)
  3. Add the configuration to the mcpServers section
  4. Restart Claude Code to apply changes

README

View on GitHub

Email MCP Server

standard-readme compliant license npm version npm downloads CI

An MCP (Model Context Protocol) server providing comprehensive email capabilities via IMAP and SMTP.

Enables AI assistants to read, search, send, manage, schedule, and analyze emails across multiple accounts. Exposes 47 tools, 7 prompts, and 6 resources over the MCP protocol with OAuth2 support (experimental), email scheduling, calendar extraction, analytics, provider-aware label management, real-time IMAP IDLE watcher with AI-powered triage, customizable presets and static rules, and a guided setup wizard.

Highlights

Featureemail-mcpTypical MCP email
Multi-account✅❌
Send / reply / forward✅✅
Drafts & templates✅❌
Labels & bulk ops✅ provider-aware❌
Schedule future emails✅❌
Real-time IMAP IDLE watcher✅❌
AI triage with presets✅❌
Desktop & webhook alerts✅❌
Calendar (ICS) extraction✅❌
Email analytics✅❌
OAuth2 (Gmail / M365)✅ experimental❌
Guided setup wizard✅ auto-detect❌

Table of Contents

Security

  • All connections use TLS/STARTTLS encryption
  • Passwords are never logged; audit trail records operations without credentials
  • Token-bucket rate limiter prevents abuse (configurable per account)
  • OAuth2 XOAUTH2 authentication for Gmail and Microsoft 365 (experimental)
  • Attachment downloads capped at 5 MB with base64 encoding

Background

Most MCP email implementations provide only basic read/send. This server aims to be a full-featured email client for AI assistants, covering the entire lifecycle: reading, composing, managing, scheduling, and analyzing email — all from a single MCP server.

Key design decisions:

  • XDG-compliant config — TOML at ~/.config/email-mcp/config.toml
  • Multi-account — Operate across multiple IMAP/SMTP accounts simultaneously
  • Layered services — Business logic is decoupled from MCP wiring for testability
  • Provider auto-detection — Gmail, Outlook, Yahoo, iCloud, Fastmail, ProtonMail, Zoho, GMX

Install

Requires Node.js ≥ 22.

# Run directly (no install needed)
npx @codefuturist/email-mcp setup
# or
pnpm dlx @codefuturist/email-mcp setup

# Or install globally
npm install -g @codefuturist/email-mcp
# or
pnpm add -g @codefuturist/email-mcp

Docker

No Node.js required — just Docker.

# Latest stable release
docker pull ghcr.io/codefuturist/email-mcp:latest

# Pin to an exact version (immutable)
docker pull ghcr.io/codefuturist/email-mcp:0.2.3

# Auto-update patches within a minor version
docker pull ghcr.io/codefuturist/email-mcp:0.2

# Track a major version (won't cross breaking-change boundary)
docker pull ghcr.io/codefuturist/email-mcp:0

# Pin to an exact git commit (immutable, CI traceability)
docker pull ghcr.io/codefuturist/email-mcp:sha-abc1234

# Or build from source
docker build -t ghcr.io/codefuturist/email-mcp .

Tag convention: Tags follow bare semver (no v prefix), matching Docker ecosystem standards (e.g. node:24, nginx:1.25). The latest tag is only updated on stable releases, never pre-releases.

Note: The server uses stdio transport. Config must be created on the host first (via npx @codefuturist/email-mcp setup or manually) and mounted into the container.

Usage

Setup

# Add an email account interactively (recommended)
email-mcp account add

# Or use the legacy alias
email-mcp setup

# Or create a template config manually
email-mcp config init

The setup wizard auto-detects server settings, tests connections, saves config, and outputs the MCP client config snippet.

Test Connections

email-mcp test            # all accounts
email-mcp test personal   # specific account

Configure Your MCP Client

Recommended — use the guided installer (auto-detects Claude Desktop, VS Code, Cursor, Windsurf):

email-mcp install

Or add manually using the snippets below.

<details> <summary><strong>Claude Desktop</strong></summary>

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "@codefuturist/email-mcp", "stdio"]
    }
  }
}
</details> <details> <summary><strong>VS Code (GitHub Copilot)</strong></summary>

Option 1 — Extensions gallery (easiest):

  1. Open the Extensions view (<kbd>⇧⌘X</kbd> / <kbd>Ctrl+Shift+X</kbd>)
  2. Search @mcp email-mcp
  3. Click Install (user-wide) or right-click → Install in Workspace

Option 2 — Workspace config (.vscode/mcp.json, committed to source control):

{
  "servers": {
    "email": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@codefuturist/email-mcp", "stdio"]
    }
  }
}

Option 3 — User config (settings.json, applies to all workspaces):

Open the Command Palette → Preferences: Open User Settings (JSON) and add:

{
  "mcp": {
    "servers": {
      "email": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@codefuturist/email-mcp", "stdio"]
      }
    }
  }
}
</details> <details> <summary><strong>Cursor</strong></summary>

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "@codefuturist/email-mcp", "stdio"]
    }
  }
}
</details> <details> <summary><strong>Windsurf</strong></summary>

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "@codefuturist/email-mcp", "stdio"]
    }
  }
}
</details> <details> <summary><strong>Zed</strong></summary>

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "email": {
      "command": {
        "path": "npx",
        "args": ["-y", "@codefuturist/email-mcp", "stdio"]
      }
    }
  }
}
</details> <details> <summary><strong>Mistral Vibe</strong></summary>

Add to ~/.vibe/config.toml:

[[mcp_servers]]
name = "email-mcp"
transport = "stdio"
command = "npx"
args = ["-y", "@codefuturist/email-mcp", "stdio"]

To pass credentials directly instead of using a config file, use the env field:

[[mcp_servers]]
name = "email-mcp"
transport = "stdio"
command = "npx"
args = ["-y", "@codefuturist/email-mcp", "stdio"]
env = { "EMAIL_ACCOUNTS" = "<your-accounts-json>" }

MCP tools are exposed as email-mcp_<tool_name> (e.g. email-mcp_list_emails). Restart Vibe after editing the config.

</details> <details> <summary><strong>Docker (any MCP client)</strong></summary>

Run the server in a container — mount your config directory read-only:

docker run --rm -i \
  -v ~/.config/email-mcp:/home/node/.config/email-mcp:ro \
  ghcr.io/codefuturist/email-mcp

For MCP client configuration (e.g. Claude Desktop):

{
  "mcpServers": {
    "email": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "~/.config/email-mcp:/home/node/.config/email-mcp:ro",
        "ghcr.io/codefuturist/email-mcp"
      ]
    }
  }
}
</details> <details> <summary><strong>Single-account via environment variables (no config file needed)</strong></summary> 
{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "@codefuturist/email-mcp", "stdio"],
      "env": {
        "MCP_EMAIL_ADDRESS": "you@gmail.com",
        "MCP_EMAIL_PASSWORD": "your-app-password",
        "MCP_EMAIL_IMAP_HOST": "imap.gmail.com",
        "MCP_EMAIL_SMTP_HOST": "smtp.gmail.com"
      }
    }
  }
}
</details>

CLI Commands

email-mcp [command]

Commands:
  stdio                     Run as MCP server over stdio (default)
  account list              List all configured accounts
  account add               Add a new email account interactively
  account edit [name]       Edit an existing account
  account delete [name]     Remove an account
  setup                     Alias for 'account add'
  test                      Test connections for all or a specific account
  install                   Register email-mcp with MCP clients interactively
  install status            Show registration status for detected clients
  install remove            Unregister email-mcp from MCP clients
  config show               Show config (passwords masked)
  config edit               Edit global settings (rate limit, read-only)
  config path               Print config file path
  config init               Create template config
  scheduler check           Process pending scheduled emails
  scheduler list            Show all scheduled emails
  scheduler install         Install OS-level scheduler (launchd/crontab)
  scheduler uninstall       Remove OS-level scheduler
  scheduler status          Show scheduler installation status
  help                      Show help

Configuration

Located at $XDG_CONFIG_HOME/email-mcp/config.toml (default: ~/.config/email-mcp/config.toml).

[settings]
rate_limit = 10  # max emails per minute per account

[[accounts]]
name = "personal"
email = "you@gmail.com"
full_name = "Your Name"
password = "your-app-password"

[accounts.imap]
host = "imap.gmail.com"
port = 993
tls = true

[accounts.smtp]
host = "smtp.gmail.com"
port = 465
tls = true
starttls = false
verify_ssl = true

[accounts.smtp.pool]
enabled = true
max_connections = 1
max_messages = 100

OAuth2 (experimental)

Note: OAuth2 support is experimental. Token refresh and provider-specific flows may require additional testing in your environment.

[[accounts]]
name = "work"
email = "you@company.com"
full_name = "Your Name"

[accounts.oauth2]
provider = "google"            # or "microsoft"
client_id = "your-client-id"
client_secret = "your-client-secret"
refresh_token = "your-refresh-token"

[accounts.imap]
host = "imap.gmail.com"
port = 993
tls = true

[accounts.smtp]
host = "smtp.gmail.com"
port = 465
tls = true

[accounts.smtp.pool]
enabled = true
max_connections = 1
max_messages = 100

Environment Variables

For single-account setups (overrides config file):

VariableDefaultDescription
MCP_EMAIL_ADDRESSrequiredEmail address
MCP_EMAIL_PASSWORDrequiredPassword or app password
MCP_EMAIL_IMAP_HOSTrequiredIMAP server hostname
MCP_EMAIL_SMTP_HOSTrequiredSMTP server hostname
MCP_EMAIL_ACCOUNT_NAMEdefaultAccount name
MCP_EMAIL_FULL_NAME—Display name
MCP_EMAIL_USERNAMEemailLogin username
MCP_EMAIL_IMAP_PORT993IMAP port
MCP_EMAIL_IMAP_TLStrueIMAP TLS
MCP_EMAIL_SMTP_PORT465SMTP port
MCP_EMAIL_SMTP_TLStrueSMTP TLS
MCP_EMAIL_SMTP_STARTTLSfalseSMTP STARTTLS
MCP_EMAIL_SMTP_VERIFY_SSLtrueVerify SSL certificates
`MCP_EMAIL

…

View source on GitHub

You might also like

Agenticmail
MCP Servers
Agentmail Toolkit
MCP Servers
Clawaimail
MCP Servers