codefuturist/email-mcp

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
| Feature | email-mcp | Typical MCP email |
|---------|:---------:|:-----------------:|
| Multi-account | ✅ | ❌ |
| Send / reply / forward | ✅ | ✅ |
| Drafts & templates | ✅ | ❌ |
| Labels & bulk ops | ✅ provider-aware | ❌ |
| Schedule future emails | ✅ | ❌ |
| Real-time IMAP IDLE watcher | ✅ | ❌ |
| Verification codes → clipboard | ✅ concealed + auto-clear | ❌ |
| AI triage with presets | ✅ | ❌ |
| Desktop & webhook alerts | ✅ | ❌ |
| Calendar (ICS) extraction | ✅ | ❌ |
| Email analytics | ✅ | ❌ |
| OAuth2 (Gmail / M365) | ✅ _experimental_ | ❌ |
| Guided setup wizard | ✅ auto-detect | ❌ |
| Streamable HTTP transport | ✅ | ❌ |
Table of Contents
- Highlights
- Security
- Background
- Install
- Usage
- API
- 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 ≥ 22.
Homebrew (native binary)
The prebuilt, dependency-free binary — no Node.js at runtime — from the
codefuturist tap:
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:
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:
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.
> **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.