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
- Outlook: Enable 2FA, then go to https://account.microsoft.com/security > Advanced security options > App passwords
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 | Auto-Discovery | IMAP | SMTP |
|---|---|---|---|
| Gmail | imap.gmail.com:993 |
TLS | TLS (465) |
| Outlook/Hotmail/Live | outlook.office365.com:993 |
TLS | STARTTLS (587) |
| Yahoo | imap.mail.yahoo.com:993 |
TLS | TLS (465) |
| iCloud/Me.com | imap.mail.me.com:993 |
TLS | STARTTLS (587) |
| Zoho | imap.zoho.com:993 |
TLS | TLS (465) |
| ProtonMail | imap.protonmail.ch:993 |
TLS | TLS (465) |
| Custom | Via email:pass:imap.host format |
Configurable | Auto-derived |
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
