better-email-mcp

- Multi-account support-- manage 6+ email accounts (Gmail, Outlook, Yahoo, iCloud, Zoho, ProtonMail, custom IMAP)
- App Passwords-- no OAuth2 setup required for most providers; clone and run in 1 minute
- 4 composite toolswith 22 actions (plushelp+config__open_relay) -- search, read, send, reply, forward, organize, and credential setup in single calls
- Auto-discovery-- provider settings detected from email address, custom IMAP host supported
- Thread-aware-- reply/forward maintains In-Reply-To and References headers
- Tiered token optimization-- compressed descriptions + on-demandhelptool + MCP Resources

The server runs in two modes:stdio(default, single-user, credentials from env vars) andHTTP(opt-in, multi-user with OAuth 2.1). For stdio, add it to your MCP client config:

Most providers use anApp Password(no OAuth setup); Outlook/Hotmail/Live use a bundled OAuth device-code flow in HTTP mode. Settings (IMAP/SMTP host, port) are auto-discovered from the email domain.

The package ships one binary,better-email-mcp(run vianpx @n24q02m/better-email-mcp). With no arguments it starts the MCP server over stdio; it also accepts one flag and one subcommand:

# stdio server (normally launched by your MCP client, not by hand) EMAIL_CREDENTIALS="user@gmail.com:app-password" npx @n24q02m/better-email-mcp # HTTP multi-user server npx @n24q02m/better-email-mcp --http # One-off Outlook OAuth device-code sign-in npx @n24q02m/better-email-mcp auth user@outlook.com # Sign out of a single account (or omit the email to clear all) npx @n24q02m/better-email-mcp logout user@outlook.com

Install with AI agent-- paste this to your AI coding agent:

The publicsendtool is replaced bymessageswithaction: new,reply, orforward. This follows the MCP N+2 standard: sending is an action in the messages domain, so keeping a separatesendentry would duplicate that domain and add redundant tool-list and help-topic surface. The old name is removed directly; there is no compatibility alias.

How better-email-mcp stacks up against direct competitors in each pillar:

Run as a multi-user HTTP server with OAuth 2.1 authentication:

{ "mcpServers": { "better-email": { "type": "http", "url": "https://<your-host>/mcp" } } }

Single multi-user mode (relay form for App-Password providers + bundled Outlook OAuth device-code):

docker run -p 8080:8080 \ -e PORT=8080 \ -e PUBLIC_URL=https://your-domain.com \ n24q02m/better-email-mcp:latest

Users provide their own email credentials through the OAuth flow / paste form. No server-sideEMAIL_CREDENTIALSneeded. With the default Docker self-host, per-user credentials are held in an in-memory store (cleared on restart); users re-submit after a restart. Outlook OAuth uses the bundled public Azure client (d56f8c71-9f7c-43f4-9934-be29cb6e77b0, Thunderbird-pattern) -- no user-side Azure app registration needed.

Self-hostable as a per-user serverless instance on Cloudflare Workers + Containers: each JWTsubgets its own Container Durable Object, and all credentials AND Outlook OAuth tokens are AES-256-GCM encrypted into Workers KV (onesubs/<sub>/configblob per user) so theysurvive scale-to-zero / container recreate with no re-auth. The JWT signing key is derived deterministically fromCREDENTIAL_SECRET(EdDSA), so the user's identity is stable across recreate. Required secrets:CREDENTIAL_SECRET(per-sub vault + EdDSA),MCP_RELAY_PASSWORD(form gate),MCP_DCR_SERVER_SECRET(intentional multi-user deploy). Seewrangler.jsonc.

Keying Outlook tokens by JWTsub(in the per-sub KV blob) resolves the former email-keyedtokens.jsonambiguity (CLAUDE.md Known Bug #4): two users' Outlook accounts can no longer collide.

Caveat:localhostIMAP accounts (email:pass:localhost:1993) are valid for local / VM deployments but CANNOT work on Cloudflare — there is no co-located IMAP proxy inside the container. Use a publicly-reachable IMAP host on CF.

In HTTP mode, Outlook/Hotmail/Live accounts use OAuth2 device-code automatically. On first use:

OAuth uses the bundled public Azure client (d56f8c71-9f7c-43f4-9934-be29cb6e77b0, Thunderbird-pattern) -- no user-side Azure registration needed.

Instdio mode, Outlook accounts use anApp Passwordinstead (Outlook Account Settings → Security → Advanced security options → App passwords).

To trust mise configuration automatically, settrusted_config_pathsin the user-level config at~/.config/mise/config.toml; do not add it to this project's.mise.toml.

EMAIL_CREDENTIALS=user1@gmail.com:pass1,user2@outlook.com:pass2,user3@yahoo.com:pass3

# Custom hostname (default port 993, implicit TLS) EMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com # Custom hostname with a custom port EMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com:1993 # Local IMAP proxy -- "localhost" is accepted as a host, even without a dot EMAIL_CREDENTIALS=user@custom.com:password:localhost:1993

A mailbox in a Microsoft 365 organisation -- including one on your own domain -- signs in through Entra ID rather than the consumer directory, and Microsoft disabled basic auth for Exchange Online in 2024, so an App Password is not an option. Two settings make it work:

OUTLOOK_TENANTapplies to the token refresh as well as the initial sign-in -- refreshing a work/school token against the consumer directory fails withAADSTS7000012: The grant was obtained for a different tenant.

If the mailbox was consented with a narrower grant (say IMAP but no SMTP), match it withOUTLOOK_SCOPESso the refresh does not ask for more than was granted.

- Credential sanitization-- Passwords never leaked in error messages
- App Passwords-- Uses app-specific passwords, not regular passwords
- Token storage-- Outlook OAuth tokens saved with 600 permissions
- IMAP validation-- Search queries validated before execution

git clone https://github.com/n24q02m/better-email-mcp.git cd better-email-mcp bun install bun run dev

Run your own multi-user better-email instance serverless on Cloudflare (Containers + KV). Each JWTsubgets its own Container Durable Object, and every user's email credentials and Outlook OAuth tokens are AES-256-GCM encrypted into a single Workers KV blob per user, so they survive scale-to-zero / container recreate with no re-auth.

Prerequisites:a Cloudflare account on theWorkers Paid plan— required for Containers (the Cloudflare free tier does not include Containers) — and thewranglerCLI.
- git clone https://github.com/n24q02m/better-email-mcp && cd better-email-mcp
- wrangler login
- Create the KV namespace (better-email is KV-only -- no D1 / Vectorize):

wrangler kv namespace create better-email-kv

docker pull ghcr.io/n24q02m/better-email-mcp:beta docker tag ghcr.io/n24q02m/better-email-mcp:beta better-email-mcp:beta wrangler containers push better-email-mcp:beta # prints registry.cloudflare.com/<ACCOUNT_ID>/better-email-mcp:beta

wrangler secret put CREDENTIAL_SECRET # per-sub vault key + deterministic EdDSA signing (required) wrangler secret put MCP_RELAY_PASSWORD # gate for the /authorize setup form wrangler secret put MCP_DCR_SERVER_SECRET # proof of an intentional multi-user deploy

Fast MCP server for Apple Mail with batch JXA (87x faster) and FTS5 search index (700-3500x faster).

Read, organise and send from the IMAP email accounts you already have. Nothing sends without your approval.

A seamless email management interface powered by Claude.

Automate email tasks using SMTP and IMAP protocols.

Local email connectivity for AI agents — read, draft, send, and organize Outlook mail via MCP. Apache-2.0 licensed.

An email processing server that uses MongoDB for semantic search and SQLite for efficient storage and retrieval.

Read, search, and manage emails from your inbox, including downloading attachments and listing folders.

Interact with Fastmail email, contacts, and calendar data using the Fastmail API.

Integrate your Fastmail account with AI assistants using the Model Context Protocol.