Allows searching, reading, and sending emails through Gmail accounts using IMAP and SMTP protocols with support for App Passwords.
Provides tools for managing emails on iCloud and Me.com accounts, including searching, reading, sending, and organizing messages via IMAP/SMTP.
Enables interaction with ProtonMail accounts through the ProtonMail Bridge, supporting operations like searching, reading, and sending emails.
Supports email operations for Zoho Mail accounts, allowing users to search, read, send, and organize messages via IMAP and SMTP.
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) |
Related MCP server: WET - Web Extended Toolkit
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 |
|
|
npx |
|
|
pnpm |
|
|
yarn |
|
|
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:pass3Custom IMAP Host
EMAIL_CREDENTIALS=user@custom.com:password:imap.custom.comTools
Tool | Actions |
| search, read, mark_read, mark_unread, flag, unflag, move, archive, trash |
| list |
| list, download |
| new, reply, forward |
| Get full documentation for any tool |
Search Query Language
Query | Description |
| Unread emails |
| Starred emails |
| Emails after date |
| Emails from sender |
| Emails matching subject |
| Compound filter |
| Compound filter |
Token Optimization
Tiered descriptions for minimal context usage:
Tier | Purpose | When |
Tier 1 | Compressed descriptions | Always loaded |
Tier 2 | Full docs via | On-demand |
Tier 3 | MCP Resources | Supported clients |
{"name": "help", "tool_name": "messages"}MCP Resources (Tier 3)
URI | Description |
| Messages tool docs |
| Folders tool docs |
| Attachments tool docs |
| Send tool docs |
Supported Providers
Provider | Auth | IMAP / SMTP | 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 | 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_IDenv 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 buildRequirements: Node.js 24+, Bun
Compatible With
Also by n24q02m
Server | Description | Install |
Notion API for AI agents |
| |
Web search, content extraction, library docs |
| |
Persistent AI memory with hybrid search |
| |
Godot Engine for AI agents |
|
Contributing
See CONTRIBUTING.md
License
MIT - See LICENSE