Better Email MCP

IMAP/SMTP MCP Server for Email - Optimized for AI Agents

Why "Better"?

5 composite tools that provide full email operations (search, read, send, reply, forward, organize) across multiple accounts using IMAP/SMTP with App Passwords.

Key Features

| Feature | Description | |---------|-------------| | Multi-Account | Manage 6+ email accounts simultaneously | | App Passwords | No OAuth2 setup required - clone and run in 1 minute | | Auto-Discovery | Gmail, Outlook, Yahoo, iCloud, Zoho, ProtonMail auto-configured | | Clean Text | HTML stripped for LLM token savings | | Thread Support | Reply/forward maintains In-Reply-To and References headers | | Composite Tools | 5 tools with 15 actions (not 15+ separate endpoints) |

Quick Start

Prerequisites

Create App Passwords (NOT your regular password):

• Gmail: Enable 2FA, then https://myaccount.google.com/apppasswords
• Yahoo: Enable 2FA, then https://login.yahoo.com/account/security/app-passwords
• iCloud: https://appleid.apple.com > Sign-In and Security > App-Specific Passwords
• Outlook/Hotmail/Live: OAuth2 built-in (server guides you on first use)

Option 1: Package Manager (Recommended)

{
  "mcpServers": {
    "better-email": {
      "command": "bun",
      "args": ["x", "@n24q02m/better-email-mcp@latest"],
      "env": {
        "EMAIL_CREDENTIALS": "[email protected]:abcd-efgh-ijkl-mnop"
      }
    }
  }
}

Alternatively, you can use npx, pnpm dlx, or yarn dlx:

| Runner | command | args | |--------|-----------|--------| | npx | npx | ["-y", "@n24q02m/better-email-mcp@latest"] | | pnpm | pnpm | ["dlx", "@n24q02m/better-email-mcp@latest"] | | yarn | yarn | ["dlx", "@n24q02m/better-email-mcp@latest"] |

Option 2: Docker

{
  "mcpServers": {
    "better-email": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--name", "mcp-email",
        "-e", "EMAIL_CREDENTIALS",
        "n24q02m/better-email-mcp:latest"
      ],
      "env": {
        "EMAIL_CREDENTIALS": "[email protected]:abcd-efgh-ijkl-mnop"
      }
    }
  }
}

Multiple Accounts

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

Custom IMAP Host

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

Tools

| Tool | Actions | |------|---------| | messages | search, read, mark_read, mark_unread, flag, unflag, move, archive, trash | | folders | list | | attachments | list, download | | send | new, reply, forward | | help | Get full documentation for any tool |

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 | | UNREAD FROM [email protected] | Compound filter |

Token Optimization

Tiered descriptions for minimal context usage:

| Tier | Purpose | When | |------|---------|------| | Tier 1 | Compressed descriptions | Always loaded | | Tier 2 | Full docs via help tool | On-demand | | Tier 3 | MCP Resources | Supported clients |

{"name": "help", "tool_name": "messages"}

MCP Resources (Tier 3)

| URI | Description | |-----|-------------| | email://docs/messages | Messages tool docs | | email://docs/folders | Folders tool docs | | email://docs/attachments | Attachments tool docs | | email://docs/send | Send tool docs |

Supported Providers

| Provider | Auth | IMAP / SMTP | Save-to-Sent | |----------|------|-------------|-------------| | Gmail | App Password | imap.gmail.com:993 / TLS (465) | Auto (skipped) | | Yahoo | App Password | imap.mail.yahoo.com:993 / TLS (465) | Auto (skipped) | | iCloud/Me.com | App-Specific Password | imap.mail.me.com:993 / STARTTLS (587) | Auto (skipped) | | Outlook/Hotmail/Live | OAuth2 (Device Code) | outlook.office365.com:993 / STARTTLS (587) | IMAP APPEND | | Zoho | App Password | imap.zoho.com:993 / TLS (465) | IMAP APPEND | | ProtonMail | ProtonMail Bridge | imap.protonmail.ch:993 / TLS (465) | IMAP APPEND | | Custom | Via email:pass:imap.host format | Configurable | IMAP APPEND |

Outlook OAuth2

Outlook.com / Hotmail / Live accounts use OAuth2 automatically — just add the email to EMAIL_CREDENTIALS. On first use, the server returns a sign-in link and code. Open the link, enter the code, then retry your request. Tokens are saved to ~/.better-email-mcp/tokens.json and auto-refresh silently.

Self-hosting with your own client ID? Set OUTLOOK_CLIENT_ID env var. See Azure Setup for details.

Build from Source

git clone https://github.com/n24q02m/better-email-mcp
cd better-email-mcp
mise run setup
bun run build

Requirements: Node.js 24+, Bun

Compatible With

Also by n24q02m

| Server | Description | Install | |--------|-------------|---------| | better-notion-mcp | Notion API for AI agents | npx -y @n24q02m/better-notion-mcp@latest | | wet-mcp | Web search, content extraction, library docs | uvx --python 3.13 wet-mcp@latest | | mnemo-mcp | Persistent AI memory with hybrid search | uvx mnemo-mcp@latest | | better-godot-mcp | Godot Engine for AI agents | npx -y @n24q02m/better-godot-mcp@latest |

Contributing

See CONTRIBUTING.md

License

MIT - See LICENSE