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

CI codecov npm Docker License: MIT

TypeScript Node.js IMAP/SMTP semantic-release Renovate

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

Setup

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

Zero-Config Setup

No environment variables needed. On first start, the server opens a relay setup page:

1. Start the server (via plugin, npx, or Docker)
2. A setup URL appears -- open it in any browser (relay: https://better-email-mcp.n24q02m.com)
3. Enter your credentials in email:app-password format (comma-separated for multi-account)
4. Credentials are encrypted and stored locally

Your credentials never leave your machine. The relay server only sees encrypted data.

For CI/automation, you can still use environment variables (see below).

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)

docker run -p 8080:8080 \
  -e TRANSPORT_MODE=http \
  -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. No server-side EMAIL_CREDENTIALS needed.

Outlook OAuth Device Code

Outlook, Hotmail, and Live accounts use OAuth2 automatically. On first use with an Outlook account:

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 saved locally at ~/.better-email-mcp/tokens.json

No App Password is needed for Outlook accounts.

Configuration

Variable	Required	Default	Description
EMAIL_CREDENTIALS	Yes (stdio)	-	Email credentials ([email protected]:app-password, comma-separated for multi-account)
TRANSPORT_MODE	No	stdio	Set to http for remote mode
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
OUTLOOK_CLIENT_ID	No	-	Custom Azure AD client ID for self-hosted Outlook OAuth2

Multiple Accounts

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

Custom IMAP Host

[email protected]:password:imap.custom.com

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

License

MIT -- See LICENSE.