convez.ai
MCP ServerAutomaçãoIntermediário
n24q02m

Better Email MCP

n24q02m/better-email-mcp

Servidor IMAP/SMTP para agentes IA com multi-conta e auto-discovery

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor 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-mcp

1 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

Estrelas
38
Forks
20
Acompanhando
0
Saúde
100%
Último commit
há 1 dia
Versão
v1.44.0
Issues abertas
1
Contribuidores
7

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

CI codecov npm Docker License: MIT

TypeScript Node.js IMAP/SMTP semantic-release Renovate

ProjectTaglineTag
better-code-review-graphKnowledge graph for token-efficient code reviews -- fixed search, configurabl...MCP
better-email-mcpIMAP/SMTP email server for AI agents -- 6 composite tools with multi-account ...MCP
better-godot-mcpComposite MCP server for Godot Engine -- 17 mega-tools for AI-assisted game d...MCP
better-notion-mcpMarkdown-first Notion API server for AI agents -- 10 composite tools replacin...MCP
better-telegram-mcpMCP server for Telegram with dual-mode support: Bot API (httpx) for quick bot...MCP
claude-pluginsFull documentation: mcp.n24q02m.com — unified docs for all 8 servers + the mc...Marketplace
imagine-mcpProduction-grade MCP server for image and video understanding + generation ac...MCP
jules-task-archiverChrome Extension for bulk operations on Jules tasks via batchexecute API -- a...Tooling
mcp-coreUnified MCP Streamable HTTP 2025-11-25 transport, OAuth 2.1 Authorization Ser...MCP
mnemo-mcpPersistent AI memory with hybrid search and embedded sync. Open, free, unlimi...MCP
qwen3-embedLightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUFLibrary
skretSecrets without the server.CLI
web-coreShared web infrastructure package for search, scraping, HTTP security, and st...Library
wet-mcpOpen-source MCP Server for web search, content extraction, library docs & mul...MCP

Table of contents

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 help tool + 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:

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-mcp following the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-email-mcp/setup-with-agent.md

Tools

ToolActionsDescription
messagessearch, read, mark_read, mark_unread, flag, unflag, move, archive, trashSearch, read, and organize emails
folderslistList mailbox folders
attachmentslist, downloadList and download email attachments
sendnew, reply, forwardCompose, reply, and forward emails
setupstatus, start, reset, completeCredential setup via browser relay, status check, reset, re-resolve
help-Get full documentation for any tool

MCP Resources

URIDescription
email://docs/messagesMessage operations reference
email://docs/foldersFolder operations reference
email://docs/attachmentsAttachment operations reference
email://docs/sendSend/compose reference
email://docs/helpFull 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:

  1. The server prints a device code and a Microsoft login URL
  2. Open the URL in a browser and enter the code
  3. Sign in and authorize the app
  4. 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

VariableRequiredDefaultDescription
EMAIL_PROVIDERYes (stdio, single-account)-Provider key: gmail, outlook, yahoo, icloud, zoho, custom
EMAIL_USERYes (stdio, single-account)-Email address
EMAIL_APP_PASSWORDYes (stdio, single-account)-App password (Gmail/Yahoo/iCloud) or Outlook App Password
EMAIL_IMAP_HOSTNo (custom only)-Custom IMAP hostname when EMAIL_PROVIDER=custom
EMAIL_CREDENTIALSAlternative (multi-account)-Legacy user@gmail.com:app-password (comma-separated for multi-account)
PUBLIC_URLNo (http)-Server's public URL for relay / OAuth redirect links
CREDENTIAL_SECRETNo (http)auto-generatedSecret used to encrypt the per-user credential store; if unset, a random 32-byte secret is generated and persisted to a 0600 file
PORTNo0 (OS-assigned)Server port (http mode); set explicitly (e.g. 8080) to bind a fixed port
HOSTNo-Bind address (http mode)
MCP_AUTH_DISABLENo (http)-Set to 1 to skip Bearer JWT verification when behind an external auth gateway
OUTLOOK_CLIENT_IDNod56f8c71-9f7c-43f4-9934-be29cb6e77b0 (bundled public client)Override the bundled Azure AD public client for self-hosted Outlook OAuth2
OUTLOOK_EMAILNo-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

QueryDescription
UNREADUnread emails
FLAGGEDStarred emails
SINCE 2024-01-01Emails after date
FROM boss@company.comEmails from sender
SUBJECT meetingEmails matching subject
UNREAD SINCE 2024-06-01Compound filter

Supported Providers

ProviderAuthSave-to-Sent
GmailApp PasswordAuto (skipped)
YahooApp PasswordAuto (skipped)
iCloud/Me.comApp-Specific PasswordAuto (skipped)
Outlook/Hotmail/LiveOAuth2 (Device Code)IMAP APPEND
ZohoApp PasswordIMAP APPEND
ProtonMailProtonMail BridgeIMAP APPEND
CustomVia email:pass:imap.hostIMAP 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.

ModeStorageEncryptionWho can read your data?
HTTP n24q02m-hosted (default)In-memory Map<sub, OAuthToken>In-process onlyServer process (cleared on restart)
HTTP self-hostSame as hostedSameOnly you (admin = user)
stdio proxy~/.better-email-mcp/config.jsonAES-GCM, machine-bound keyOnly your OS user (file perm 0600)

License

MIT -- See LICENSE.

Ver o original no GitHub

Bom para

Relacionados