Email MCP

Email MCP Server

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 52 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, instant verification-code catching with clipboard copy, customizable presets and static rules, and a guided setup wizard.

Built on the MCP TypeScript SDK v2 (spec revision 2026-07-28), it serves over stdio for local clients or Streamable HTTP for networked access — existing stdio configurations keep working unchanged.

Highlights

Table of Contents

• Highlights
• Security
• Background
• Install
• Usage
• API
• Roadmap
• Maintainers
• Contributing
• License

Security

• All connections use TLS/STARTTLS encryption
• Passwords are never logged; audit trail records operations without credentials
• Token-bucket rate limiter prevents abuse (one bucket per account, sharing a global rate_limit)
• 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 ≥ 24.

# 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

npm install -g fails with EACCES when npm's global prefix is a root-owned directory (common on a system Node install) — the npx/pnpm dlx form above avoids this entirely by not installing anything globally. If you do want a permanent global install, fix npm's prefix instead of reaching for sudo (npm config set prefix ~/.npm-global and add that to PATH, or use a Node version manager like nvm/fnm/volta) — running npm install -g as root routinely leaves root-owned files mixed into a user-owned node_modules tree, which causes harder-to-diagnose permission errors on the *next* global install.

Homebrew (native binary)

The prebuilt, dependency-free binary — no Node.js at runtime — from the codefuturist tap:

brew install codefuturist/tap/email-mcp

Published as a cask on every stable release; works on macOS (arm64 + x64) and on Linuxbrew ≥ 4.3 (binary-only casks).

Native binary (Bun)

A dependency-free single binary (minified + bytecode-precompiled, ~32 ms cold start, no Node.js at runtime) can be compiled with Bun:

bun run build:binary          # native binary → build/email-mcp

cp build/email-mcp ~/.local/bin/

bun run build:binaries # release matrix: darwin-arm64/x64, linux-x64/arm64,

windows-x64 → build/release/*.{tar.gz,zip} + sha256 checksums

Prebuilt binaries for every release are built by CI with GoReleaser Pro (.goreleaser.yaml) for all common platforms — Linux glibc + musl, macOS, and Windows, each x64 + arm64 where Bun supports it — provenance-attested (verify with gh attestation verify --repo codefuturist/email-mcp) and shipped with GitHub releases — installable via mise: mise use -g ubi:codefuturist/email-mcp.

The same binary can also be built locally from the published npm package (no checkout needed; ≥ 0.5.1, which carries the imapflow TLS fix at runtime — older versions need the repo's pnpm patch). Note that a plain bun add -g shim executes dist/main.js under node via its shebang, so the compile step is what buys the ~11 ms cold start:

bun add -g @codefuturist/email-mcp

bun build --compile --minify --bytecode \ "${BUN_INSTALL:-$HOME/.bun}/install/global/node_modules/@codefuturist/email-mcp/dist/main.js" \ --outfile ~/.local/bin/email-mcp

An installed binary keeps itself current: email-mcp update checks the latest release and — after a confirmation, a sha256 check against the release's checksums file, and (when the gh CLI is present) a provenance-attestation check — atomically replaces itself. --check only reports (exit code 1 = update available), --yes skips the prompt for scripts. npm- and mise-managed installs are recognized and pointed at npm install -g …@latest / mise upgrade instead of being overwritten.

server install from the binary points the launchd login item at it. Requires the bundled imapflow patch (patches/) — imapflow passes servername: false to tls.connect for IP hosts, which Bun's stricter node:tls rejects.

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: By default, 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)

On macOS and Linux this offers to store the password in the OS keychain,

so config.toml only carries a keychain: reference.

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

The snippets below use the default stdio transport, best for local desktop clients. For networked or remote access over Streamable HTTP, see Streamable HTTP (networked) below.

Recommended — use the guided installer (auto-detects Claude Desktop, Cursor, Windsurf; for VS Code use the manual snippet below):

email-mcp install

Or add manually using the snippets below.

Claude Desktop

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>

VS Code (GitHub Copilot)

Option 1 — Extensions gallery (easiest):

1. Open the Extensions view ( ⇧⌘X / Ctrl+Shift+X )
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>

Cursor

Edit ~/.cursor/mcp.json:

{

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

</details>

Windsurf

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

{

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

</details>

Zed

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

{

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

</details>

Mistral Vibe

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" = " " }

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

Docker (any MCP client)

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 \ -v email-mcp-state:/home/node/.local/state/email-mcp \ -v email-mcp-cache:/home/node/.cache/email-mcp \ ghcr.io/codefuturist/email-mcp

The config mount can