better-email-mcp

email

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

IMAP/SMTP email for AI agents -- read, send, organize, and manage attachments across accounts.

Sister projects from n24q02m (click to expand)

Project	Tagline	Tag
agent-chat-plugin	Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor...	Tooling
better-code-review-graph	Knowledge graph for token-efficient code reviews -- semantic search and call-...	MCP
better-drive	2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray	Tooling
better-email-mcp	IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att...	MCP
better-godot-mcp	Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g...	MCP
better-notion-mcp	Markdown-first Notion for AI agents -- pages, databases, blocks, and comments...	MCP
better-semantic-release	Drop-in python-semantic-release fork with built-in release-safety guards (orp...	Tooling
better-telegram-mcp	Telegram for AI agents -- messages, chats, media, and contacts across both bo...	MCP
better-workspace-mcp	Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...	MCP
claude-plugins	Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea...	Marketplace
imagine-mcp	Image and video understanding + generation for AI agents -- across Gemini, Op...	MCP
jules-task-archiver	Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a...	Tooling
mcp-core	Shared foundation for building MCP servers -- Streamable HTTP transport, OAut...	MCP
mnemo-mcp	Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi...	MCP
qwen3-embed	Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF	Library
skret	Secrets without the server.	CLI
tacet	A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl...	Tooling
web-core	Shared web infrastructure package for search, scraping, HTTP security, and st...	Library
wet-mcp	Open-source MCP server for AI agents: web search, content extraction, and lib...	MCP

Table of contents

• Features
• Install
• CLI
• Smithery
• Documentation
• Tools
• Comparison
• Remote (HTTP Mode)
• Outlook OAuth Device Code (HTTP mode)
• Configuration
• Security
• Build from Source
• 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
• 4 composite tools with 23 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": {
    "email": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/email@latest"],
      "env": {
        "EMAIL_CREDENTIALS": "user@gmail.com:app-password"
      }
    }
  }
}

The package is @n24q02m/email (formerly @n24q02m/better-email-mcp; old package receives one final release then freezes). The MCP Registry id stays io.github.n24q02m/better-email-mcp, and the legacy better-email-mcp command is kept as an alias of email.

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.

Install matrix

Client	Install
Claude Code	/plugin marketplace add n24q02m/claude-plugins + /plugin install better-email-mcp@n24q02m-plugins (stdio; prompts for EMAIL_CREDENTIALS), or an mcpServers entry in .mcp.json / client settings
Codex CLI	[mcp_servers.email] block in ~/.codex/config.toml (stdio command/args or HTTP type/url)
OpenCode	mcpServers block in opencode.json
Cursor / Windsurf / Gemini CLI / any MCP client	mcpServers JSON in the client's config — same shape as the example above

Full per-client walkthroughs: mcp.n24q02m.com/servers/better-email-mcp/setup/.

CLI

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

Invocation	Description
email	Start the MCP server over stdio (default). Reads credentials from EMAIL_CREDENTIALS, or from EMAIL_USER + EMAIL_APP_PASSWORD
email --http	Start the server in HTTP (multi-user, OAuth 2.1) mode. Equivalent to MCP_TRANSPORT=http or TRANSPORT_MODE=http
email auth [outlook] <email> [--client-id=<id>]	Authenticate an Outlook/Hotmail/Live account via OAuth2 Device Code flow. Tokens are saved to ~/.better-email-mcp/tokens.json. The outlook provider positional is optional (email has a single OAuth2 provider); --client-id overrides OUTLOOK_CLIENT_ID for a self-hosted Azure AD app
email logout [<email>]	Clear the locally stored Outlook token(s). Omit <email> to clear every stored token

# stdio server (normally launched by your MCP client, not by hand)
EMAIL_CREDENTIALS="user@gmail.com:app-password" npx @n24q02m/email

# HTTP multi-user server
npx @n24q02m/email --http

# One-off Outlook OAuth device-code sign-in
npx @n24q02m/email auth user@outlook.com

# Sign out of a single account (or omit the email to clear all)
npx @n24q02m/email 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 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/email'] })

Documentation

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

• 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 email following the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-email-mcp/setup-with-agent.md

Tools

Public tool rename

The public send tool is replaced by messages with action: new, reply, or forward. This follows the MCP N+2 standard: sending is an action in the messages domain, so keeping a separate send entry would duplicate that domain and add redundant tool-list and help-topic surface. The old name is removed directly; there is no compatibility alias.

Old public name	New public name	Reason	Alias removal
send	messages (action: new | reply | forward)	N+2 domain-tool rule: outbound mail is part of the messages mega-tool, not a second action-level tool.	Removed directly in the Unreleased release; no alias

Tool	Actions	Description
messages	search, read, mark_read, mark_unread, flag, unflag, move, archive, trash, new, reply, forward	Search, read, organize, compose, reply to, and forward emails
folders	list, status	List mailbox folders or read targeted IMAP STATUS metadata
attachments	list, download	List and download email attachments
config	status, setup_status, setup_start, setup_reset, setup_complete, set, cache_clear	Credential setup via browser relay, status check, reset, re-resolve, cache clear
config__open_relay	-	Open the relay configuration form in the browser and return the relay URL
help	-	Get full documentation for any tool

MCP Resources

URI	Description
email://docs/messages	Message operations reference
email://docs/folders	Folder operations reference
email://docs/attachments	Attachment operations reference
email://docs/help	Full documentation
email://docs/config	Credential setup and runtime configuration reference

Comparison

How email stacks up against direct competitors in each pillar:

Capability	email	email-mcp	Gmail-MCP-Server	mcp-mail-server
IMAP/SMTP (provider-agnostic)	Yes	Yes	No (Gmail API only)	Yes
Multi-account	Yes (comma-separated creds)	Yes	No (single global credential)	No (single account per instance)
App Passwords	Yes (no OAuth setup)	Yes	No (OAuth2 only)	Yes
Auto-discovery from email address	Yes	Yes (8 providers)	n/a (Gmail only)	No (manual host/port)
Bundled Outlook OAuth (no user Azure app)	Yes (device-code, Thunderbird-pattern client)	partial (OAuth2 XOAUTH2, experimental)	No (user-supplied Google OAuth)	No
Attachments (list + download)	Yes	Yes	Yes	Yes
HTTP multi-user mode (per-JWT-sub)	Yes (OAuth 2.1, self-hostable)	No (stdio only)	No (stdio only)	No (stdio only)

Remote (HTTP Mode)

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

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

Self-Hosting (HTTP Mode)

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

export CREDENTIAL_SECRET='replace-with-a-stable-secret'
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e PUBLIC_URL=https://your-domain.com \
  -e MCP_STORAGE_BACKEND=local \
  -e HOME=/data \
  -e CREDENTIAL_SECRET="$CREDENTIAL_SECRET" \
  -v email-data:/data \
  n24q02m/email:latest

Users provide their own email credentials through the OAuth flow / paste form. No server-side EMAIL_CREDENTIALS is needed. The stable CREDENTIAL_SECRET encrypts the local per-user credential files; the mounted /data volume survives container restarts. Without that volume, the container filesystem remains ephemeral.

Self-Hosting with Docker Compose

The repository ships docker-compose.http.yml, which builds the http image target and publishes it on host loopback only (127.0.0.1:8082):

export CREDENTIAL_SECRET='replace-with-a-stable-secret'   # per-user vault key + deterministic EdDSA JWT signing (required)
export MCP_RELAY_PASSWORD='replace-with-a-form-password'  # gate for the /authorize setup form
docker compose -f docker-compose.http.yml up

The server is then reachable at http://localhost:8082. To serve other machines, put your own TLS reverse proxy on the same host in front of the loopback port and set PUBLIC_URL to the public HTTPS origin. Prebuilt multi-arch images are published to Docker Hub (n24q02m/email) and GHCR (ghcr.io/n24q02m/email).

The JWT signing key is derived deterministically from CREDENTIAL_SECRET (EdDSA), so user identity stays stable across container recreation. Per-user credentials and Outlook tokens are keyed by JWT sub, so two users' Outlook accounts cannot collide.

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 local credential files ($HOME/.better-email-mcp/subs/<sub>/config.json) on a self-hosted HTTP deploy with a /data volume, in the local in-memory store otherwise, 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

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

Variable	Required	Default	Description
EMAIL_CREDENTIALS	Yes (stdio)	-	Email credentials, email:app-password per account, comma-separated for multi-account. Optional custom IMAP host/port: email:password:imap_host:imap_port
EMAIL_USER	Alternative (stdio, single-account)	-	Email address. Used with EMAIL_APP_PASSWORD as a per-field alternative to EMAIL_CREDENTIALS; merged into EMAIL_CREDENTIALS at boot
EMAIL_APP_PASSWORD	Alternative (stdio, single-account)	-	App password (Gmail/Yahoo/iCloud) or Outlook App Password; used with EMAIL_USER
PUBLIC_URL	No (http)	-	Server's public URL for relay / OAuth redirect links
PORT	No	0 (OS-assigned)	Server port (http mode); set explicitly (e.g. 8080) to bind a fixed port
HOST	No	-	Bind address (http mode)
MCP_AUTH_DISABLE	No (http)	-	Set to 1 to skip Bearer JWT verification when behind an external auth gateway
OUTLOOK_CLIENT_ID	No	d56f8c71-9f7c-43f4-9934-be29cb6e77b0 (bundled public client)	Override the bundled Azure AD public client for self-hosted Outlook OAuth2 (or --client-id=<id> on auth, which overrides this env var)
OUTLOOK_EMAIL	No	-	Workaround when Microsoft device-code response omits the email field
OUTLOOK_TENANT	No	consumers (stdio/CLI), common (http device-code)	Microsoft directory to sign in against, used for both the device-code and the token-refresh endpoint. Set common for a work/school (Entra ID) mailbox, or a tenant GUID / verified domain to pin one directory
OUTLOOK_SCOPES	No	https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/SMTP.Send offline_access	Space-separated scope list. Narrow it (e.g. drop SMTP.Send) for a read-only deployment — a grant consented with fewer scopes cannot be refreshed against the full list
OUTLOOK_EXTRA_DOMAINS	No	-	Comma-separated domains routed to OAuth in addition to outlook.com/hotmail.com/live.com. Needed for a Microsoft 365 mailbox on your own domain, which otherwise looks like a password account

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).

Microsoft 365 work/school accounts

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:

# Sign in against the directory that owns the mailbox
OUTLOOK_TENANT=common                      # or a tenant GUID / verified domain

# Route your own domain to OAuth instead of asking for a password
OUTLOOK_EXTRA_DOMAINS=company.com

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

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

Search Query Language

Query	Description
UNREAD	Unread emails
FLAGGED	Starred emails
SINCE 2024-01-01	Emails after date
FROM boss@company.com	Emails from sender
SUBJECT meeting	Emails matching subject
UNREAD SINCE 2024-06-01	Compound filter

Supported Providers

Provider	Auth	Save-to-Sent
Gmail	App Password	Auto (skipped)
Yahoo	App Password	Auto (skipped)
iCloud/Me.com	App-Specific Password	Auto (skipped)
Outlook/Hotmail/Live	OAuth2 (Device Code)	IMAP APPEND
Zoho	App Password	IMAP APPEND
ProtonMail	ProtonMail Bridge	IMAP APPEND
Custom	Via email:pass:imap.host	IMAP APPEND

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/email.git
cd email
bun install
bun run dev

Trust Model

This plugin implements TC-NearZK. Storage durability depends on the deployment mode; see the mcp-core trust model for full classification.

Mode	Storage	Encryption	Who can read your data?
HTTP local Docker	Encrypted local files under $HOME/.better-email-mcp/subs/<sub>/config.json	AES-256-GCM	Server operator (admin = user)
stdio	platformdirs mcp config dir (config.enc; e.g. %APPDATA%\mcp\Config\config.enc on Windows)	AES-GCM, machine-bound key	Only your OS user (file perm 0600)

License

Apache-2.0 -- See LICENSE.