Better Email MCP

mcp-name: io.github.n24q02m/better-email-mcp

IMAP/SMTP email for AI agents -- read, send, organize folders, and manage attachments across multiple accounts, with auto-discovery.

Table of contents

• Features
• Install
• CLI
• Smithery
• Documentation
• Tools
• Comparison
• Remote (HTTP Mode)
• Outlook OAuth Device Code (HTTP mode)
• Configuration
• Security
• Build from Source
• Deploy to Cloudflare
• Trust Model
• License

Features

• 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
• 5 composite tools with 21 actions (plus help + 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-demand help tool + MCP Resources

Install

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

{
  "mcpServers": {
    "better-email": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/better-email-mcp@latest"],
      "env": {
        "EMAIL_CREDENTIALS": "user@gmail.com:app-password"
      }
    }
  }
}

Multiple accounts are comma-separated: user1@gmail.com:pass1,user2@outlook.com:pass2. See Configuration for all env vars, and Remote (HTTP Mode) to run a hosted multi-user server.

Most providers use an App 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.

CLI

The package ships one binary, better-email-mcp (run via npx @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

auth/logout are only for Outlook/Hotmail/Live addresses -- other providers use an App Password in EMAIL_CREDENTIALS. See Remote (HTTP Mode) for the hosted endpoint and HTTP config.

Smithery

Published with a Smithery config (smithery.yaml). Smithery runs the server over stdio with no build config required; credentials are supplied at runtime through the server's own setup flow (see Configuration). The start command is:

startCommand:
  type: stdio
  commandFunction: |-
    (config) => ({ command: 'npx', args: ['-y', '@n24q02m/better-email-mcp'] })

Documentation

Full docs at mcp.n24q02m.com/servers/better-email-mcp/setup/:

• Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
• Modes overview -- stdio (default) and HTTP (opt-in, multi-user with OAuth 2.1)
• Multi-user setup -- per-JWT-sub credential model

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

Install MCP server better-email-mcp following the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-email-mcp/setup-with-agent.md

Tools

MCP Resources

Comparison

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

Remote (HTTP Mode)

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

{
  "mcpServers": {
    "better-email": {
      "type": "http",
      "url": "https://email.n24q02m.com/mcp"
    }
  }
}

Self-Hosting (HTTP Mode)

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-side EMAIL_CREDENTIALS needed. 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.

Cloudflare serverless mode (KV-only)

Deploy a per-user serverless instance at https://email.n24q02m.com: each JWT sub gets its own Container Durable Object, and all credentials AND Outlook OAuth tokens are AES-256-GCM encrypted into Workers KV (one subs/<sub>/config blob per user) so they survive scale-to-zero / container recreate with no re-auth. The JWT signing key is derived deterministically from CREDENTIAL_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). See wrangler.jsonc.

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

Caveat: localhost IMAP 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.

Outlook OAuth Device Code (HTTP mode)

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

1. The server prints a device code and a Microsoft login URL
2. Open the URL in a browser and enter the code
3. Sign in and authorize the app
4. Tokens are persisted per JWT sub — in the encrypted Cloudflare KV credential blob (subs/<sub>/config) on the serverless deploy, or in ~/.better-email-mcp/tokens.json for single-user / stdio

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

In stdio mode, Outlook accounts use an App Password instead (Outlook Account Settings → Security → Advanced security options → App passwords).

Configuration

Multiple Accounts

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

Custom IMAP Host

# 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

Each account can use its own host and port. A non-993 port is treated as plaintext/STARTTLS -- the usual shape for a local IMAP proxy (for example email-oauth2-proxy).

Search Query Language

Supported Providers

Security

• 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

Build from Source

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

Deploy to Cloudflare

Run your own multi-user better-email instance serverless on Cloudflare (Containers + KV). Each JWT sub gets 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 the Workers Paid plan — required for Containers (the Cloudflare free tier does not include Containers) — and the wrangler CLI.

1. git clone https://github.com/n24q02m/better-email-mcp && cd better-email-mcp
2. wrangler login
3. Create the KV namespace (better-email is KV-only -- no D1 / Vectorize):
   code

   wrangler kv namespace create better-email-kv
   

   Paste the returned id into <better-email-kv-namespace-id> in wrangler.jsonc.
4. Push the container image to your Cloudflare managed registry (CF Containers cannot pull from external registries directly), then set <YOUR_ACCOUNT_ID> in wrangler.jsonc:
   code

   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
   

5. Point wrangler.jsonc at your own domain: set <YOUR_PUBLIC_URL> (e.g. https://email.example.com) and <YOUR_WORKER_DOMAIN> (e.g. email.example.com).
6. Set the deploy secrets:
   code

   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
   

   Optional Outlook overrides -- only to replace the bundled public Azure device-code client (default needs no user-side Azure app): wrangler secret put OUTLOOK_CLIENT_ID and wrangler secret put OUTLOOK_EMAIL.
7. wrangler deploy, then open <YOUR_PUBLIC_URL>/authorize and complete the browser relay form.

End-users supply their own email credentials -- an App Password via the paste form, or the bundled Outlook device-code sign-in -- through that relay form; there is no server-side EMAIL_CREDENTIALS. Storage maps to Cloudflare via MCP_STORAGE_BACKEND=cf-kv (already set in wrangler.jsonc); see Cloudflare serverless mode (KV-only) for the encryption and trust details.

Trust Model

This plugin implements TC-NearZK (in-memory, ephemeral). See the mcp-core trust model for full classification.

License

MIT -- See LICENSE.