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": "user@gmail.com: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": "user@gmail.com:abcd-efgh-ijkl-mnop"
      }
    }
  }
}

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

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 boss@company.com`	Emails from sender
`SUBJECT meeting`	Emails matching subject
`UNREAD SINCE 2024-06-01`	Compound filter
`UNREAD FROM boss@company.com`	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`
better-telegram-mcp	Telegram Bot API + MTProto for AI agents	`uvx --python 3.13 better-telegram-mcp@latest`

Contributing

See CONTRIBUTING.md

License

MIT - See LICENSE