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

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

MCP Resources

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

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

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

License

MIT -- See LICENSE.