How do I install Better Email?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Better Email need an API key?

The publisher lists these environment variables: EMAIL_CREDENTIALS.

What transport does Better Email use?

Better Email runs locally over stdio.

When was Better Email last checked?

Last checked 2026-10-28. IMAP/SMTP MCP server for Email with composite tools. Multi-account, auto-discovery.

Better Email MCP server

email

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

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 (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

Install

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": "[email protected]: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: [email protected]:pass1,[email protected]: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 (single-user, bearer token) 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="[email protected]: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 [email protected]

# Sign out of a single account (or omit the email to clear all)
npx @n24q02m/email logout [email protected]

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 come from the environment (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

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 status and setup guidance, reset, re-resolve, cache clear
`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 mode (single-user, bearer token; self-hostable)	Yes	No (stdio only)	No (stdio only)	No (stdio only)

Remote (HTTP Mode)

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"
    }
  }
}

Self-Hosting (HTTP Mode)

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='[email protected]: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:latest

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

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 EMAIL_MCP_TOKEN_HASH='scrypt$...'   # required; see the note above
export EMAIL_CREDENTIALS='[email protected]:app-password'
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. Prebuilt multi-arch images are published to Docker Hub (n24q02m/email) and GHCR (ghcr.io/n24q02m/email).

Outlook OAuth Device Code

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

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`
`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)
`EMAIL_MCP_TOKEN_HASH`	No (http; required when not bound to loopback)	-	scrypt hash of the shared bearer token, minted with `email token hash`. Without it, HTTP runs unauthenticated only on loopback
`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	-

Multiple Accounts

[email protected]:pass1,[email protected]:pass2,[email protected]:pass3

Custom IMAP Host

# Custom hostname (default port 993, implicit TLS)
[email protected]:password:imap.custom.com

# Custom hostname with a custom port
[email protected]:password:imap.custom.com:1993

# Local IMAP proxy -- "localhost" is accepted as a host, even without a dot
[email protected]: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 [email protected]`	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 are written with mode 0600 on POSIX (not enforced on Windows)
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

Credentials 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 (`EMAIL_CREDENTIALS`) and saved Outlook tokens in `$HOME/.better-email-mcp/tokens.json` (the `/data` volume)	Tokens: plain JSON, POSIX file mode 0600	Server operator
stdio	Env vars; saved Outlook tokens in `~/.better-email-mcp/tokens.json`; legacy `config.enc` from earlier releases is still read	Tokens: plain JSON, POSIX file mode 0600	Only your OS user

License

Apache-2.0 -- See LICENSE.

Better Email

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Better Email?

Does Better Email need an API key?

What transport does Better Email use?

When was Better Email last checked?

Documentation

email

Table of contents

Features

Install

Install matrix

CLI

Smithery

Documentation

Tools

Public tool rename

MCP Resources

Comparison

Remote (HTTP Mode)

Self-Hosting (HTTP Mode)

Self-Hosting with Docker Compose

Outlook OAuth Device Code

Configuration

Multiple Accounts

Custom IMAP Host

Microsoft 365 work/school accounts

Search Query Language

Supported Providers

Security

Build from Source

Trust Model

License