email

email

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

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

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": "[email protected]:app-password"
      }
    }
  }
}

The package is @n24q02m/email (formerly @n24q02m/better-email-mcp; old packagereceives one final release then freezes). The MCP Registry id staysio.github.n24q02m/better-email-mcp, and the legacy better-email-mcp command iskept 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

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:

# 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 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 athttps://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 aseparate send entry would duplicate that domain and add redundant tool-list and help-topicsurface. The old name is removed directly; there is no compatibility alias.

MCP Resources

Comparison

How email stacks up against direct competitors in each pillar:

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 andpublishes 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 ownTLS reverse proxy on the same host in front of the loopback port and set PUBLIC_URL to thepublic 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 useridentity stays stable across container recreation. Per-user credentials and Outlook tokens arekeyed 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.

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 asplaintext/STARTTLS -- the usual shape for a local IMAP proxy (for exampleemail-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 Microsoftdisabled basic auth for Exchange Online in 2024, so an App Password is not anoption. 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 withAADSTS7000012: The grant was obtained for a different tenant.

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

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

License

Apache-2.0 -- See LICENSE.