Better Email MCP

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

IMAP/SMTP email server for AI agents -- 6 composite tools with multi-account and auto-discovery

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
6 composite tools with 20 actions -- search, read, send, reply, forward, organize, 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

Status

2026-05-02 -- Architecture stabilization update

Past months saw significant churn around credential handling and the daemon-bridge auto-spawn pattern. This caused multi-process races, browser tab spam, and inconsistent setup UX across plugins. As of v<auto>, the architecture is stable: 2 clean modes (stdio + HTTP), no daemon-bridge layer, no auto-spawn from stdio.

Apologies for the instability period. If you encountered issues with prior versions, please update to v<auto>+ and follow the current docs/setup-manual.md -- most prior workarounds are no longer needed.

Related plugins from the same author:

wet-mcp -- Web search + content extraction

mnemo-mcp -- Persistent AI memory

imagine-mcp -- Image/video understanding + generation

better-notion-mcp -- Notion API

better-email-mcp -- Email management

better-telegram-mcp -- Telegram

better-godot-mcp -- Godot Engine

better-code-review-graph -- Code review knowledge graph

All plugins share the same architecture -- install once, learn pattern transfers.

Setup

Stdio mode (default) -- env var creds (EMAIL_PROVIDER + EMAIL_USER + EMAIL_APP_PASSWORD), single-user local. See setup-manual.md.
HTTP mode (optional, encouraged) -- multi-user, browser-based setup with bundled Outlook OAuth. See setup-manual.md "Method 5: Self-Hosting HTTP Mode".

With AI Agent -- copy and send this to your AI agent:

Please set up @n24q02m/better-email-mcp for me. Follow this guide:
https://raw.githubusercontent.com/n24q02m/better-email-mcp/main/docs/setup-with-agent.md

Manual Setup -- follow docs/setup-manual.md

Tools

Tool	Actions	Description
`messages`	`search`, `read`, `mark_read`, `mark_unread`, `flag`, `unflag`, `move`, `archive`, `trash`	Search, read, and organize emails
`folders`	`list`	List mailbox folders
`attachments`	`list`, `download`	List and download email attachments
`send`	`new`, `reply`, `forward`	Compose, reply, and forward emails
`setup`	`status`, `start`, `reset`, `complete`	Credential setup via browser relay, status check, reset, re-resolve
`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/send`	Send/compose reference
`email://docs/help`	Full documentation

Remote (HTTP Mode)

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

{
  "mcpServers": {
    "better-email": {
      "type": "http",
      "url": "https://better-email-mcp.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 PUBLIC_URL=https://your-domain.com \
  -e DCR_SERVER_SECRET=$(openssl rand -hex 32) \
  n24q02m/better-email-mcp:latest

Users provide their own email credentials through the OAuth flow / paste form. No server-side EMAIL_CREDENTIALS needed. Outlook OAuth uses the bundled public Azure client (d56f8c71-9f7c-43f4-9934-be29cb6e77b0, Thunderbird-pattern) -- no user-side Azure app registration needed.

Outlook OAuth Device Code (HTTP mode)

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

The server 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 persisted per JWT sub (tokens/<sub>.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

Variable	Required	Default	Description
`EMAIL_PROVIDER`	Yes (stdio, single-account)	-	Provider key: `gmail`, `outlook`, `yahoo`, `icloud`, `zoho`, `custom`
`EMAIL_USER`	Yes (stdio, single-account)	-	Email address
`EMAIL_APP_PASSWORD`	Yes (stdio, single-account)	-	App password (Gmail/Yahoo/iCloud) or Outlook App Password
`EMAIL_IMAP_HOST`	No (custom only)	-	Custom IMAP hostname when `EMAIL_PROVIDER=custom`
`EMAIL_CREDENTIALS`	Alternative (multi-account)	-	Legacy `user@gmail.com:app-password` (comma-separated for multi-account)
`PUBLIC_URL`	Yes (http)	-	Server's public URL for OAuth redirects
`DCR_SERVER_SECRET`	Yes (http)	-	HMAC secret for stateless client registration
`PORT`	No	`8080`	Server port (http mode)
`OUTLOOK_CLIENT_ID`	No	`d56f8c71-9f7c-43f4-9934-be29cb6e77b0` (bundled public client)	Override the bundled Azure AD public client for self-hosted Outlook OAuth2
`OUTLOOK_EMAIL`	No	-	Workaround when Microsoft device-code response omits the email field

Multiple Accounts

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

Custom IMAP Host

EMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com

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

Trust Model

This plugin implements TC-NearZK (in-memory, ephemeral). See mcp-core/docs/TRUST-MODEL.md for full classification.

Mode	Storage	Encryption	Who can read your data?
HTTP n24q02m-hosted (default)	In-memory `Map<sub, OAuthToken>`	In-process only	Server process (cleared on restart)
HTTP self-host	Same as hosted	Same	Only you (admin = user)
stdio proxy	`~/.better-email-mcp/config.json`	AES-GCM, machine-bound key	Only your OS user (file perm 0600)

License

MIT -- See LICENSE.