README.md
IMAP/SMTP email server for AI agents with multi-account and auto-discovery
Better Email MCP
IMAP/SMTP email server for AI agents -- 5 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
- 5 composite tools with 15 actions -- search, read, send, reply, forward, organize 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
helptool + MCP Resources
Quick Start
Claude Code Plugin (Recommended)
claude plugin add n24q02m/better-email-mcp
After install, set your credentials: claude config set mcpServers.better-email-mcp.env.EMAIL_CREDENTIALS "user@gmail.com:app-password". See Prerequisites below for how to create App Passwords.
MCP Server
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: npx
{
"mcpServers": {
"better-email": {
"command": "npx",
"args": ["-y", "@n24q02m/better-email-mcp@latest"],
"env": {
"EMAIL_CREDENTIALS": "user@gmail.com:abcd-efgh-ijkl-mnop"
}
}
}
}
Other runners: bun x, pnpm dlx, yarn dlx also work.
Option 2: Docker
{
"mcpServers": {
"better-email": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-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 | Description |
|---|---|---|
messages |
search, read, mark_read, mark_unread, flag, unflag, move, archive, trash |
Search, read, and organize emails |
folders |
list |
List mailbox folders |
attachments |
list, download |
List and download email attachments |
send |
new, reply, forward |
Compose, reply, and forward emails |
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 |
Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
EMAIL_CREDENTIALS |
Yes | - | Email credentials (user@gmail.com:app-password, comma-separated for multi-account) |
OUTLOOK_CLIENT_ID |
No | - | Custom Azure AD client ID |
Tools (5)
messagesSearch, read, and organize emails using actions like search, read, mark_read, mark_unread, flag, unflag, move, archive, and trash.foldersList mailbox folders.attachmentsList and download email attachments.sendCompose, reply, and forward emails.helpGet full documentation for any tool.Environment Variables
EMAIL_CREDENTIALSrequiredEmail credentials (user@gmail.com:app-password), comma-separated for multi-account.OUTLOOK_CLIENT_IDCustom Azure AD client ID for Outlook.Configuration
claude_desktop_config.json
{"mcpServers": {"better-email": {"command": "npx", "args": ["-y", "@n24q02m/better-email-mcp@latest"], "env": {"EMAIL_CREDENTIALS": "user@gmail.com:abcd-efgh-ijkl-mnop"}}}}Try it
→Search for unread emails from my boss received since last week.
→Find the latest email with an attachment and download it.
→Reply to the most recent email in my inbox confirming I received the document.
→Move all emails with the subject 'Project Update' to the 'Work' folder.
→List all folders in my primary email account.