Better Email MCP lets AI agents operate IMAP/SMTP email accounts: search/read/organize messages, inspect folders, manage attachments, send/reply/forward mail, and fetch tool documentation.
Messages: search by query/folder/account; read single or batch UIDs; mark read/unread; flag/unflag; move, archive, or trash emails.
Folders: list mailbox folders for one account or all accounts, including names, paths, and flags.
Attachments: list attachments for an email and download a chosen attachment as base64 content.
Send: compose new emails, reply with thread headers and auto Re:, or forward with original body and auto Fwd:, supporting to/cc/bcc/subject/body.
Help: retrieve full documentation for any exposed tool.
Schema note: the provided schema exposes send separately and does not include new/reply/forward under messages, differing from the README’s rename note.
Allows searching, reading, and sending emails through Gmail accounts using IMAP and SMTP protocols with support for App Passwords.
Provides tools for managing emails on iCloud and Me.com accounts, including searching, reading, sending, and organizing messages via IMAP/SMTP.
Enables interaction with ProtonMail accounts through the ProtonMail Bridge, supporting operations like searching, reading, and sending emails.
Supports email operations for Zoho Mail accounts, allowing users to search, read, send, and organize messages via IMAP and SMTP.
mcp-name: io.github.n24q02m/better-email-mcp
IMAP/SMTP email for AI agents -- read, send, organize, and manage attachments across accounts.
Project | Tagline | Tag |
Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling | |
Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP | |
2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling | |
IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP | |
Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP | |
Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP | |
Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling | |
Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP | |
Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP | |
Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace | |
Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP | |
Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling | |
Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP | |
Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP | |
Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library | |
Secrets without the server. | CLI | |
A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling | |
Shared web infrastructure package for search, scraping, HTTP security, and st... | Library | |
Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |
Related MCP server: WET - Web Extended Toolkit
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 (plus help) -- search, read, send, reply, forward, organize, and credential status 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
The server runs in two modes: stdio (default, single-user, credentials from env vars) and HTTP (opt-in, single-user with a bearer token). 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.
Client | Install |
Claude Code |
|
Codex CLI |
|
OpenCode |
|
Cursor / Windsurf / Gemini CLI / any MCP client |
|
Full per-client walkthroughs: docs.n24q02m.com/servers/email/setup/.
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 |
| Start the MCP server over stdio (default). Reads credentials from |
| Start the server in HTTP (single-user, bearer token) mode. Equivalent to |
| Authenticate an Outlook/Hotmail/Live account via OAuth2 Device Code flow. Tokens are saved to |
| Clear the locally stored Outlook token(s). Omit |
# 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.comauth/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.
Published with a Smithery config (smithery.yaml). Smithery runs the server over stdio with no build config required; credentials come from the environment (see Configuration). The start command is:
startCommand:
type: stdio
commandFunction: |-
(config) => ({ command: 'npx', args: ['-y', '@n24q02m/email'] })Full docs at docs.n24q02m.com/servers/email/:
Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
Install with AI agent -- paste this to your AI coding agent:
Install MCP server
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 |
|
| N+2 domain-tool rule: outbound mail is part of the | Removed directly in the Unreleased release; no alias |
Tool | Actions | Description |
|
| Search, read, organize, compose, reply to, and forward emails |
|
| List mailbox folders or read targeted IMAP STATUS metadata |
|
| List and download email attachments |
|
| Credential status and setup guidance, reset, re-resolve, cache clear |
| - | Get full documentation for any tool |
URI | Description |
| Message operations reference |
| Folder operations reference |
| Attachment operations reference |
| Full documentation |
| Credential setup and runtime configuration reference |
How email stacks up against direct competitors in each pillar:
Capability | ||||
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 mode (single-user, bearer token; self-hostable) | Yes | No (stdio only) | No (stdio only) | No (stdio only) |
Run as a single-user HTTP server, authenticated with a shared bearer token:
{
"mcpServers": {
"email": {
"type": "http",
"headers": { "Authorization": "Bearer <your-token>" },
"url": "https://<your-host>/mcp"
}
}
}Single-user mode: one shared bearer token; accounts come from env vars or email auth outlook <address>:
export EMAIL_MCP_TOKEN_HASH='scrypt$...' # required: the container binds 0.0.0.0 and refuses to start without it
export EMAIL_CREDENTIALS='you@gmail.com:app-password'
docker run -p 8080:8080 \
-e PORT=8080 \
-e EMAIL_MCP_TOKEN_HASH \
-e EMAIL_CREDENTIALS \
-e HOME=/data \
-v email-data:/data \
n24q02m/email:latestMint the hash with printf '%s' "$TOKEN" | email token hash; the token is read from stdin, never argv. Clients send the raw token as Authorization: Bearer <token>. Saved Outlook tokens live under /data/.better-email-mcp/ and persist when the /data volume is kept.
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 EMAIL_MCP_TOKEN_HASH='scrypt$...' # required; see the note above
export EMAIL_CREDENTIALS='you@gmail.com:app-password'
docker compose -f docker-compose.http.yml upThe 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. Prebuilt multi-arch images are published to Docker Hub (n24q02m/email)
and GHCR (ghcr.io/n24q02m/email).
Outlook/Hotmail/Live accounts use OAuth2 device-code. Run email auth outlook <address> once. On first use:
The CLI prints a device code and a Microsoft login URL
Open the URL in a browser and enter the code
Sign in and authorize the app
Tokens are saved to ~/.better-email-mcp/tokens.json (created with mode 0600 on POSIX). In Docker that path is /data/.better-email-mcp/tokens.json.
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).
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 |
| Yes (stdio) | - | Email credentials, |
| Alternative (stdio, single-account) | - | Email address. Used with |
| Alternative (stdio, single-account) | - | App password (Gmail/Yahoo/iCloud) or Outlook App Password; used with |
| No |
| Server port (http mode); set explicitly (e.g. |
| No | - | Bind address (http mode) |
| No (http; required when not bound to loopback) | - | scrypt hash of the shared bearer token, minted with |
| No |
| Override the bundled Azure AD public client for self-hosted Outlook OAuth2 (or |
| No | - | Workaround when Microsoft device-code response omits the email field |
| No |
| Microsoft directory to sign in against, used for both the device-code and the token-refresh endpoint. Set |
| No |
| Space-separated scope list. Narrow it (e.g. drop |
| No | - | Comma-separated domains routed to OAuth in addition to |
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:1993Each 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).
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.comOUTLOOK_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.
Query | Description |
| Unread emails |
| Starred emails |
| Emails after date |
| Emails from sender |
| Emails matching subject |
| Compound filter |
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 | IMAP APPEND |
Credential sanitization -- Passwords never leaked in error messages
App Passwords -- Uses app-specific passwords, not regular passwords
Token storage -- Outlook OAuth tokens are written with mode 0600 on POSIX (not enforced on Windows)
IMAP validation -- Search queries validated before execution
git clone https://github.com/n24q02m/email.git
cd email
bun install
bun run devCredentials are single-user: whoever runs the server (or your OS user for stdio) can read them. Storage depends on the deployment mode:
Mode | Storage | Encryption | Who can read your data? |
HTTP (Docker) | Env vars ( | Tokens: plain JSON, POSIX file mode 0600 | Server operator |
stdio | Env vars; saved Outlook tokens in | Tokens: plain JSON, POSIX file mode 0600 | Only your OS user |
Apache-2.0 -- See LICENSE.
Email attachments: list, download. List shows all attachments for an email. Download returns base64-encoded content.
Inputs: action (required), account (required), uid (required), folder, +1 more.
List mailbox folders for one or all email accounts. Returns folder names, paths, and flags.
Inputs: action (required), account.
Get full documentation for a tool. Use when compressed descriptions are insufficient.
Inputs: tool_name (required).
Email messages: search, read, mark_read, mark_unread, flag, unflag, move, archive, trash. Search across all accounts or filter by account. Query supports: UNREAD, FLAGGED, SINCE YYYY-MM-DD, FROM x, SUBJECT x.
Inputs: action (required), account, query, folder, +4 more.
Send emails: new, reply, forward. Reply maintains thread headers (In-Reply-To, References) and auto-prepends "Re:" to subject. Forward includes original body and auto-prepends "Fwd:" to subject.
Inputs: action (required), account (required), body (required), to, +5 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 5 tools
Each tool has a clearly distinct purpose with no overlap: attachments handles attachments, folders manages mailbox folders, help provides documentation, messages handles email messages, and send sends emails. The descriptions clearly separate their domains, making misselection unlikely.
All tool names follow a consistent snake_case pattern using plural nouns (attachments, folders, messages) or verbs (help, send). This predictable naming scheme makes the tool set easy to navigate and understand.
With 5 tools, this server is well-scoped for email management. Each tool earns its place by covering distinct aspects: folder management, message handling, sending, attachments, and help. The count is neither too thin nor overwhelming for the domain.
The tool set provides comprehensive coverage for core email workflows: reading, searching, organizing, sending, and managing attachments. A minor gap exists in lacking explicit tools for account management (e.g., adding/removing accounts) or advanced message operations like deleting permanently, but agents can work around this with existing tools.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Hosted MCP server for your Gmail, Outlook and IMAP mail, with mailboxes and scopes set per agent.
Gmail, Outlook, Hotmail, Microsoft 365, iCloud, Fastmail, other IMAP mailboxes: search, read, send.
Read, send, organize, watch email on any IMAP mailbox: Gmail, iCloud, OVH, Zoho, Fastmail + CalDAV.
