Better Email MCP
n24q02m/better-email-mcp
Servidor IMAP/SMTP para agentes IA com multi-conta e auto-discovery
Ver no GitHubServidor MCP para IMAP/SMTP que permite agentes de IA gerenciar email com suporte a múltiplas contas e auto-descoberta. Oferece 6 ferramentas compostas para leitura, envio e processamento de mensagens de forma integrada ao Claude.
Instalação
npx convez-ai n24q02m/better-email-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de fluxos de email em agentes IA
- Integração de leitura/envio de emails em workflows Claude
- Processamento em lote de mensagens por agentes
- Multi-account email management para assistentes IA
Veredito

Ferramenta robusta e bem-mantida para integração de email em agentes IA. Implementação TypeScript de qualidade com CI/CD, cobertura de testes e suporte a deployment (npm, Docker), ideal para automatizar fluxos que dependem de comunicação por email.
README
A tradução para o português deste README ainda está na fila.
Better Email MCP
mcp-name: io.github.n24q02m/better-email-mcp
IMAP/SMTP email server for AI agents -- 6 composite tools with multi-account and auto-discovery
| Project | Tagline | Tag |
|---|---|---|
| better-code-review-graph | Knowledge graph for token-efficient code reviews -- fixed search, configurabl... | MCP |
| better-email-mcp | IMAP/SMTP email server for AI agents -- 6 composite tools with multi-account ... | MCP |
| better-godot-mcp | Composite MCP server for Godot Engine -- 17 mega-tools for AI-assisted game d... | MCP |
| better-notion-mcp | Markdown-first Notion API server for AI agents -- 10 composite tools replacin... | MCP |
| better-telegram-mcp | MCP server for Telegram with dual-mode support: Bot API (httpx) for quick bot... | MCP |
| claude-plugins | Full documentation: mcp.n24q02m.com — unified docs for all 8 servers + the mc... | Marketplace |
| imagine-mcp | Production-grade MCP server for image and video understanding + generation ac... | MCP |
| jules-task-archiver | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |
| mcp-core | Unified MCP Streamable HTTP 2025-11-25 transport, OAuth 2.1 Authorization Ser... | MCP |
| mnemo-mcp | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |
| qwen3-embed | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |
| skret | Secrets without the server. | CLI |
| web-core | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |
| wet-mcp | Open-source MCP Server for web search, content extraction, library docs & mul... | MCP |
Table of contents
- Features
- Status
- Documentation
- Tools
- Remote (HTTP Mode)
- Outlook OAuth Device Code (HTTP mode)
- Configuration
- Security
- Build from Source
- Trust Model
- License
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
- 6 composite tools with 20 actions -- search, read, send, reply, forward, organize, credential setup 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
Status
2026-05-02 -- Architecture stabilization update
Past months saw significant churn around credential handling and the daemon-bridge auto-spawn pattern. This caused multi-process races, browser tab spam, and inconsistent setup UX across plugins. As of v<auto>, the architecture is stable: 2 clean modes (stdio + HTTP), no daemon-bridge layer, no auto-spawn from stdio.
Apologies for the instability period. If you encountered issues with prior versions, please update to v<auto>+ and follow the current Setup guide -- most prior workarounds are no longer needed.
Related plugins from the same author:
- wet-mcp -- Web search + content extraction
- mnemo-mcp -- Persistent AI memory
- imagine-mcp -- Image/video understanding + generation
- better-notion-mcp -- Notion API
- better-email-mcp -- Email management
- better-telegram-mcp -- Telegram
- better-godot-mcp -- Godot Engine
- better-code-review-graph -- Code review knowledge graph
All plugins share the same architecture -- install once, learn pattern transfers.
Documentation
Full docs at mcp.n24q02m.com/servers/better-email-mcp/:
- Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
- Modes overview -- stdio / local-relay / remote-relay / remote-oauth
- Multi-user setup -- per-JWT-sub credential model
Install with AI agent -- paste this to your AI coding agent:
Install MCP server
better-email-mcpfollowing the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-email-mcp/setup-with-agent.md
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 |
setup | status, start, reset, complete | Credential setup via browser relay, status check, reset, re-resolve |
help | - | Get full documentation for any tool |
MCP Resources
| URI | Description |
|---|---|
email://docs/messages | Message operations reference |
email://docs/folders | Folder operations reference |
email://docs/attachments | Attachment operations reference |
email://docs/send | Send/compose reference |
email://docs/help | Full documentation |
Remote (HTTP Mode)
Run as a multi-user HTTP server with OAuth 2.1 authentication:
{
"mcpServers": {
"better-email": {
"type": "http",
"url": "https://better-email-mcp.n24q02m.com/mcp"
}
}
}
Self-Hosting (HTTP Mode)
Single multi-user mode (relay form for App-Password providers + bundled Outlook OAuth device-code):
docker run -p 8080:8080 \
-e PORT=8080 \
-e PUBLIC_URL=https://your-domain.com \
-e CREDENTIAL_SECRET=$(openssl rand -hex 32) \
n24q02m/better-email-mcp:latest
Users provide their own email credentials through the OAuth flow / paste form. No server-side EMAIL_CREDENTIALS needed. Outlook OAuth uses the bundled public Azure client (d56f8c71-9f7c-43f4-9934-be29cb6e77b0, Thunderbird-pattern) -- no user-side Azure app registration needed.
Outlook OAuth Device Code (HTTP mode)
In HTTP mode, Outlook/Hotmail/Live accounts use OAuth2 device-code automatically. On first use:
- The server prints a device code and a Microsoft login URL
- Open the URL in a browser and enter the code
- Sign in and authorize the app
- Tokens are persisted per JWT sub (
tokens/<sub>.json)
OAuth uses the bundled public Azure client (d56f8c71-9f7c-43f4-9934-be29cb6e77b0, Thunderbird-pattern) -- no user-side Azure registration needed.
In stdio mode, Outlook accounts use an App Password instead (Outlook Account Settings → Security → Advanced security options → App passwords).
Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
EMAIL_PROVIDER | Yes (stdio, single-account) | - | Provider key: gmail, outlook, yahoo, icloud, zoho, custom |
EMAIL_USER | Yes (stdio, single-account) | - | Email address |
EMAIL_APP_PASSWORD | Yes (stdio, single-account) | - | App password (Gmail/Yahoo/iCloud) or Outlook App Password |
EMAIL_IMAP_HOST | No (custom only) | - | Custom IMAP hostname when EMAIL_PROVIDER=custom |
EMAIL_CREDENTIALS | Alternative (multi-account) | - | Legacy user@gmail.com:app-password (comma-separated for multi-account) |
PUBLIC_URL | No (http) | - | Server's public URL for relay / OAuth redirect links |
CREDENTIAL_SECRET | No (http) | auto-generated | Secret used to encrypt the per-user credential store; if unset, a random 32-byte secret is generated and persisted to a 0600 file |
PORT | No | 0 (OS-assigned) | Server port (http mode); set explicitly (e.g. 8080) to bind a fixed port |
HOST | No | - | Bind address (http mode) |
MCP_AUTH_DISABLE | No (http) | - | Set to 1 to skip Bearer JWT verification when behind an external auth gateway |
OUTLOOK_CLIENT_ID | No | d56f8c71-9f7c-43f4-9934-be29cb6e77b0 (bundled public client) | Override the bundled Azure AD public client for self-hosted Outlook OAuth2 |
OUTLOOK_EMAIL | No | - | Workaround when Microsoft device-code response omits the email field |
Multiple Accounts
EMAIL_CREDENTIALS=user1@gmail.com:pass1,user2@outlook.com:pass2,user3@yahoo.com:pass3
Custom IMAP Host
# Custom hostname (default port 993, implicit TLS)
EMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com
# Custom hostname with a custom port
EMAIL_CREDENTIALS=user@custom.com:password:imap.custom.com:1993
# Local IMAP proxy -- "localhost" is accepted as a host, even without a dot
EMAIL_CREDENTIALS=user@custom.com:password:localhost:1993
Each account can use its own host and port. A non-993 port is treated as plaintext/STARTTLS -- the usual shape for a local IMAP proxy (for example email-oauth2-proxy).
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 |
Supported Providers
| Provider | Auth | 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 email:pass:imap.host | IMAP APPEND |
Security
- Credential sanitization -- Passwords never leaked in error messages
- App Passwords -- Uses app-specific passwords, not regular passwords
- Token storage -- Outlook OAuth tokens saved with 600 permissions
- IMAP validation -- Search queries validated before execution
Build from Source
git clone https://github.com/n24q02m/better-email-mcp.git
cd better-email-mcp
bun install
bun run dev
Trust Model
This plugin implements TC-NearZK (in-memory, ephemeral). See mcp-core/docs/TRUST-MODEL.md for full classification.
| Mode | Storage | Encryption | Who can read your data? |
|---|---|---|---|
| HTTP n24q02m-hosted (default) | In-memory Map<sub, OAuthToken> | In-process only | Server process (cleared on restart) |
| HTTP self-host | Same as hosted | Same | Only you (admin = user) |
| stdio proxy | ~/.better-email-mcp/config.json | AES-GCM, machine-bound key | Only your OS user (file perm 0600) |
License
MIT -- See LICENSE.