better-email-mcp

Gerenciamento de e-mail via IMAP/SMTP, multi-contas

Documentação

Better Email MCP

mcp-name: io.github.n24q02m/better-email-mcp

E-mail IMAP/SMTP para agentes de IA -- ler, enviar, organizar pastas e gerenciar anexos em várias contas, com descoberta automática.

Projetos irmãos de n24q02m (clique para expandir)

Projeto	Slogan	Tag
agent-chat-plugin	Agentes de IA pares conversam em uma pasta compartilhada — sem retransmissão humana, sem orquestrador, fun...	Ferramenta
better-code-review-graph	Grafo de conhecimento para revisões de código eficientes em tokens — busca semântica e chamadas de...	MCP
better-drive	Sincronização bidirecional do Google Drive com filtro .driveignore — mecanismo rclone, bandeja do Windows	Ferramenta
better-email-mcp	E-mail IMAP/SMTP para agentes de IA -- ler, enviar, organizar pastas e gerenciar anexos em várias contas...	MCP
better-godot-mcp	Servidor MCP composto para Godot Engine -- 17 ferramentas compostas para desenvolvimento de jogos assistido...	MCP
better-notion-mcp	Notion com foco em Markdown para agentes de IA -- páginas, bancos de dados, blocos e comentários...	MCP
better-semantic-release	Fork do python-semantic-release com proteções de segurança de lançamento integradas (orp...	Ferramenta
better-telegram-mcp	Telegram para agentes de IA -- mensagens, chats, mídia e contatos em ambos os bo...	MCP
better-workspace-mcp	Servidor MCP do Google Workspace (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...	MCP
claude-plugins	Mercado de plugins do Claude Code para os servidores MCP da n24q02m -- instalar pesquisa web...	Marketplace
imagine-mcp	Compreensão e geração de imagens e vídeos para agentes de IA -- em Gemini, Op...	MCP
jules-task-archiver	Extensão do Chrome para operações em lote em tarefas do Jules via API batchexecute -- a...	Ferramenta
mcp-core	Fundação compartilhada para construir servidores MCP -- transporte HTTP Streamable, OAut...	MCP
mnemo-mcp	Memória persistente de IA com busca híbrida e sincronização incorporada. Aberto, gratuito, ilimitado...	MCP
qwen3-embed	Incorporação e reordenação de texto Qwen3 leve via ONNX Runtime e GGUF	Biblioteca
skret	Segredos sem o servidor.	CLI
tacet	Uma cascata neuro-simbólica auto-destilante que amortiza o custo de LLM em conhecimento...	Ferramenta
web-core	Pacote de infraestrutura web compartilhada para busca, raspagem, segurança HTTP e st...	Biblioteca
wet-mcp	Servidor MCP de código aberto para agentes de IA: busca web, extração de conteúdo e lib...	MCP

Recursos

Suporte a múltiplas contas -- gerencie 6+ contas de e-mail (Gmail, Outlook, Yahoo, iCloud, Zoho, ProtonMail, IMAP personalizado)
Senhas de aplicativo -- sem necessidade de configuração OAuth2 para a maioria dos provedores; clone e execute em 1 minuto
4 ferramentas compostas com 22 ações (mais help + config__open_relay) -- buscar, ler, enviar, responder, encaminhar, organizar e configurar credenciais em chamadas únicas
Descoberta automática -- configurações do provedor detectadas a partir do endereço de e-mail, com suporte a host IMAP personalizado
Ciente de threads -- responder/encaminhar mantém os cabeçalhos In-Reply-To e References
Otimização de tokens em camadas -- descrições compactadas + ferramenta help sob demanda + Recursos MCP

Instalação

O servidor opera em dois modos: stdio (padrão, usuário único, credenciais de variáveis de ambiente) e HTTP (opt-in, multiusuário com OAuth 2.1). Para stdio, adicione-o à configuração do seu cliente MCP:

{
  "mcpServers": {
    "better-email": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/better-email-mcp@latest"],
      "env": {
        "EMAIL_CREDENTIALS": "user@gmail.com:app-password"
      }
    }
  }
}

Múltiplas contas são separadas por vírgula: user1@gmail.com:pass1,user2@outlook.com:pass2. Veja Configuration para todas as variáveis de ambiente, e Remote (HTTP Mode) para executar um servidor multiusuário hospedado.

A maioria dos provedores usa uma Senha de aplicativo (sem configuração OAuth); Outlook/Hotmail/Live usam um fluxo de código de dispositivo OAuth integrado no modo HTTP. As configurações (host IMAP/SMTP, porta) são descobertas automaticamente a partir do domínio de e-mail.

CLI

O pacote inclui um único binário, better-email-mcp (executado via npx @n24q02m/better-email-mcp). Sem argumentos, ele inicia o servidor MCP via stdio; também aceita uma flag e um subcomando:

Invocação	Descrição
`better-email-mcp`	Inicia o servidor MCP via stdio (padrão). Lê credenciais de `EMAIL_CREDENTIALS`, ou de `EMAIL_USER` + `EMAIL_APP_PASSWORD`
`better-email-mcp --http`	Inicia o servidor no modo HTTP (multiusuário, OAuth 2.1). Equivalente a `MCP_TRANSPORT=http` ou `TRANSPORT_MODE=http`
`better-email-mcp auth [outlook] <email> [--client-id=<id>]`	Autentica uma conta Outlook/Hotmail/Live via fluxo de Código de Dispositivo OAuth2. Os tokens são salvos em `~/.better-email-mcp/tokens.json`. O posicional de provedor `outlook` é opcional (o e-mail tem um único provedor OAuth2); `--client-id` substitui `OUTLOOK_CLIENT_ID` para um aplicativo Azure AD auto-hospedado
`better-email-mcp logout [<email>]`	Limpa o(s) token(s) Outlook armazenados localmente. Omita `<email>` para limpar todos os tokens armazenados

# stdio server (normally launched by your MCP client, not by hand)
EMAIL_CREDENTIALS="user@gmail.com:app-password" npx @n24q02m/better-email-mcp

# HTTP multi-user server
npx @n24q02m/better-email-mcp --http

# One-off Outlook OAuth device-code sign-in
npx @n24q02m/better-email-mcp auth user@outlook.com

# Sign out of a single account (or omit the email to clear all)
npx @n24q02m/better-email-mcp logout user@outlook.com

auth/logout são apenas para endereços Outlook/Hotmail/Live -- outros provedores usam uma Senha de aplicativo em EMAIL_CREDENTIALS. Veja Remote (HTTP Mode) para a configuração HTTP.

Smithery

Publicado com uma configuração Smithery (smithery.yaml). O Smithery executa o servidor via stdio sem necessidade de configuração de build; as credenciais são fornecidas em tempo de execução através do fluxo de configuração do próprio servidor (veja Configuration). O comando de início é:

startCommand:
  type: stdio
  commandFunction: |-
    (config) => ({ command: 'npx', args: ['-y', '@n24q02m/better-email-mcp'] })

Documentação

Documentação completa em mcp.n24q02m.com/servers/better-email-mcp/setup/:

Setup -- métodos de instalação para Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
Modes overview -- stdio (padrão) e HTTP (opt-in, multiusuário com OAuth 2.1)
Multi-user setup -- modelo de credenciais por JWT-sub

Instalar com agente de IA -- cole isto no seu agente de codificação de IA:

Instale o servidor MCP better-email-mcp seguindo os passos em https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-email-mcp/setup-with-agent.md

Ferramentas

Renomeação pública de ferramenta

A ferramenta pública send é substituída por messages com action: new, reply ou forward. Isso segue o padrão MCP N+2: enviar é uma ação no domínio de mensagens, então manter uma entrada separada send duplicaria esse domínio e adicionaria superfície redundante de lista de ferramentas e tópicos de ajuda. O nome antigo é removido diretamente; não há alias de compatibilidade.

Nome público antigo	Novo nome público	Motivo	Remoção de alias
`send`	`messages` (`action: new \| reply \| forward`)	Regra de ferramenta de domínio N+2: e-mail de saída faz parte da mega-ferramenta `messages`, não uma segunda ferramenta de nível de ação.	Removido diretamente no lançamento Unreleased; sem alias

Ferramenta	Ações	Descrição
`messages`	`search`, `read`, `mark_read`, `mark_unread`, `flag`, `unflag`, `move`, `archive`, `trash`, `new`, `reply`, `forward`	Buscar, ler, organizar, compor, responder e encaminhar e-mails
`folders`	`list`, `status`	Listar pastas da caixa de correio ou ler metadados IMAP STATUS direcionados
`attachments`	`list`, `download`	Listar e baixar anexos de e-mail
`config`	`status`, `setup_status`, `setup_start`, `setup_reset`, `setup_complete`, `set`, `cache_clear`	Configuração de credenciais via relay de navegador, verificação de status, redefinição, re-resolução, limpeza de cache
`config__open_relay`	-	Abrir o formulário de configuração do relay no navegador e retornar a URL do relay
`help`	-	Obter documentação completa para qualquer ferramenta

Recursos MCP

URI	Descrição
`email://docs/messages`	Referência de operações de mensagem
`email://docs/folders`	Referência de operações de pasta
`email://docs/attachments`	Referência de operações de anexo
`email://docs/help`	Documentação completa
`email://docs/config`	Referência de configuração de credenciais e configuração em tempo de execução

Comparação

Como o better-email-mcp se compara aos concorrentes diretos em cada pilar:

Capacidade	better-email-mcp	email-mcp	Gmail-MCP-Server	mcp-mail-server
IMAP/SMTP (agnóstico de provedor)	Sim	Sim	Não (somente API Gmail)	Sim
Múltiplas contas	Sim (credenciais separadas por vírgula)	Sim	Não (credencial global única)	Não (uma conta por instância)
Senhas de aplicativo	Sim (sem configuração OAuth)	Sim	Não (somente OAuth2)	Sim
Descoberta automática a partir do endereço de e-mail	Sim	Sim (8 provedores)	n/a (somente Gmail)	Não (host/porta manual)
OAuth Outlook integrado (sem aplicativo Azure do usuário)	Sim (código de dispositivo, cliente padrão Thunderbird)	parcial (OAuth2 XOAUTH2, experimental)	Não (OAuth Google fornecido pelo usuário)	Não
Anexos (listar + baixar)	Sim	Sim	Sim	Sim
Modo HTTP multiusuário (por JWT-sub)	Sim (OAuth 2.1, auto-hospedável)	Não (somente stdio)	Não (somente stdio)	Não (somente stdio)

Remoto (Modo HTTP)

Execute como um servidor HTTP multiusuário com autenticação OAuth 2.1:

{
  "mcpServers": {
    "better-email": {
      "type": "http",
      "url": "https://<your-host>/mcp"
    }
  }
}

Auto-hospedagem (Modo HTTP)

Modo multiusuário único (formulário de relay para provedores de Senha de aplicativo + OAuth Outlook integrado com código de dispositivo):

docker run -p 8080:8080 \
  -e PORT=8080 \
  -e PUBLIC_URL=https://your-domain.com \
  n24q02m/better-email-mcp:latest

Os usuários fornecem suas próprias credenciais de e-mail através do fluxo OAuth / formulário de colagem. Nenhum EMAIL_CREDENTIALS no lado do servidor é necessário. Com o Docker auto-hospedado padrão, as credenciais por usuário são mantidas em um armazenamento em memória (limpo no reinício); os usuários reenviam após um reinício. O OAuth Outlook usa o cliente público Azure integrado (d56f8c71-9f7c-43f4-9934-be29cb6e77b0, padrão Thunderbird) -- sem necessidade de registro de aplicativo Azure do lado do usuário.

Modo serverless Cloudflare (somente KV)

Auto-hospedável como uma instância serverless por usuário em Cloudflare Workers + Containers: cada JWT sub obtém seu próprio Container Durable Object, e todas as credenciais E tokens OAuth do Outlook são criptografados com AES-256-GCM no Workers KV (um blob subs/<sub>/config por usuário) para que sobrevivam ao scale-to-zero / recriação de contêiner sem reautenticação. A chave de assinatura JWT é derivada deterministicamente de CREDENTIAL_SECRET (EdDSA), então a identidade do usuário é estável entre recriações. Segredos necessários: CREDENTIAL_SECRET (cofre por sub + EdDSA), MCP_RELAY_PASSWORD (gate de formulário), MCP_DCR_SERVER_SECRET (implantação multiusuário intencional). Veja wrangler.jsonc.

Chavear tokens Outlook por JWT sub (no blob KV por sub) resolve a antiga ambiguidade tokens.json chaveada por e-mail (Bug Conhecido #4 do CLAUDE.md): as contas Outlook de dois usuários não podem mais colidir. Aviso: contas IMAP localhost (email:pass:localhost:1993) são válidas para implantações locais / em VM, mas NÃO funcionam no Cloudflare — não há proxy IMAP co-localizado dentro do contêiner. Use um host IMAP publicamente acessível na CF.

Outlook OAuth Device Code (modo HTTP)

No modo HTTP, contas Outlook/Hotmail/Live usam OAuth2 device-code automaticamente. No primeiro uso:

O servidor exibe um device code e uma URL de login da Microsoft
Abra a URL em um navegador e insira o código
Faça login e autorize o aplicativo
Os tokens são persistidos por sub do JWT — no blob de credenciais criptografado do Cloudflare KV (subs/<sub>/config) na implantação serverless, no armazenamento local em memória para HTTP local, ou em ~/.better-email-mcp/tokens.json para uso single-user / stdio

O OAuth usa o cliente público Azure incluído (d56f8c71-9f7c-43f4-9934-be29cb6e77b0, padrão Thunderbird) — não é necessário registro Azure do lado do usuário.

No modo stdio, contas Outlook usam uma App Password (Configurações da conta Outlook → Segurança → Opções avançadas de segurança → App passwords).

Configuração

Para confiar na configuração do mise automaticamente, defina trusted_config_paths na configuração de nível de usuário em ~/.config/mise/config.toml; não adicione ao .mise.toml deste projeto.

Variável	Obrigatório	Padrão	Descrição
`EMAIL_CREDENTIALS`	Sim (stdio)	-	Credenciais de e-mail, `email:app-password` por conta, separadas por vírgula para múltiplas contas. Host/porta IMAP personalizado opcional: `email:password:imap_host:imap_port`
`EMAIL_USER`	Alternativa (stdio, conta única)	-	Endereço de e-mail. Usado com `EMAIL_APP_PASSWORD` como alternativa por campo ao `EMAIL_CREDENTIALS`; mesclado em `EMAIL_CREDENTIALS` na inicialização
`EMAIL_APP_PASSWORD`	Alternativa (stdio, conta única)	-	App password (Gmail/Yahoo/iCloud) ou Outlook App Password; usado com `EMAIL_USER`
`PUBLIC_URL`	Não (http)	-	URL pública do servidor para relay / links de redirecionamento OAuth
`PORT`	Não	`0` (atribuída pelo SO)	Porta do servidor (modo http); defina explicitamente (ex.: `8080`) para vincular uma porta fixa
`HOST`	Não	-	Endereço de bind (modo http)
`MCP_AUTH_DISABLE`	Não (http)	-	Defina como `1` para pular a verificação Bearer JWT quando estiver atrás de um gateway de autenticação externo
`OUTLOOK_CLIENT_ID`	Não	`d56f8c71-9f7c-43f4-9934-be29cb6e77b0` (cliente público incluído)	Substitui o cliente público Azure AD incluído para Outlook OAuth2 auto-hospedado (ou `--client-id=<id>` em `auth`, que substitui esta variável de ambiente)
`OUTLOOK_EMAIL`	Não	-	Solução alternativa quando a resposta do device code da Microsoft omite o campo de e-mail
`OUTLOOK_TENANT`	Não	`consumers` (stdio/CLI), `common` (http device-code)	Diretório Microsoft para autenticação, usado para ambos o device-code e o endpoint de renovação de token. Defina `common` para uma caixa de correio corporativa/escolar (Entra ID), ou um GUID de locatário / domínio verificado para fixar um diretório
`OUTLOOK_SCOPES`	Não	`https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/SMTP.Send offline_access`	Lista de escopos separados por espaço. Reduza-a (ex.: remova `SMTP.Send`) para uma implantação somente leitura — uma concessão consentida com menos escopos não pode ser renovada contra a lista completa
`OUTLOOK_EXTRA_DOMAINS`	Não	-	Domínios separados por vírgula roteados para OAuth além de `outlook.com`/`hotmail.com`/`live.com`. Necessário para uma caixa de correio Microsoft 365 no seu próprio domínio, que de outra forma parece uma conta com senha

Múltiplas Contas

EMAIL_CREDENTIALS=user1@gmail.com:pass1,user2@outlook.com:pass2,user3@yahoo.com:pass3

Host IMAP Personalizado

# 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

Cada conta pode usar seu próprio host e porta. Uma porta diferente de 993 é tratada como texto puro/STARTTLS — o formato usual para um proxy IMAP local (por exemplo email-oauth2-proxy).

Contas corporativas/escolares Microsoft 365

Uma caixa de correio em uma organização Microsoft 365 — incluindo uma no seu próprio domínio — faz login via Entra ID em vez do diretório de consumidores, e a Microsoft desativou a autenticação básica para Exchange Online em 2024, então uma App Password não é uma opção. Duas configurações fazem funcionar:

# Sign in against the directory that owns the mailbox
OUTLOOK_TENANT=common                      # or a tenant GUID / verified domain

# Route your own domain to OAuth instead of asking for a password
OUTLOOK_EXTRA_DOMAINS=company.com

OUTLOOK_TENANT se aplica também à renovação de token, não apenas ao login inicial — renovar um token corporativo/escolar contra o diretório de consumidores falha com AADSTS7000012: The grant was obtained for a different tenant.

Se a caixa de correio foi consentida com uma concessão mais restrita (digamos IMAP mas sem SMTP), faça a correspondência com OUTLOOK_SCOPES para que a renovação não solicite mais do que foi concedido.

Linguagem de Consulta de Busca

Consulta	Descrição
`UNREAD`	E-mails não lidos
`FLAGGED`	E-mails com estrela
`SINCE 2024-01-01`	E-mails após data
`FROM boss@company.com`	E-mails do remetente
`SUBJECT meeting`	E-mails que correspondem ao assunto
`UNREAD SINCE 2024-06-01`	Filtro composto

Provedores Suportados

Provedor	Autenticação	Salvar em Enviados
Gmail	App Password	Automático (ignorado)
Yahoo	App Password	Automático (ignorado)
iCloud/Me.com	Senha específica do app	Automático (ignorado)
Outlook/Hotmail/Live	OAuth2 (Device Code)	IMAP APPEND
Zoho	App Password	IMAP APPEND
ProtonMail	ProtonMail Bridge	IMAP APPEND
Personalizado	Via `email:pass:imap.host`	IMAP APPEND

Segurança

Sanitização de credenciais — Senhas nunca vazam em mensagens de erro
App Passwords — Usa senhas específicas do aplicativo, não senhas regulares
Armazenamento de tokens — Tokens OAuth do Outlook salvos com permissões 600
Validação IMAP — Consultas de busca validadas antes da execução

Compilar a partir do Código-Fonte

git clone https://github.com/n24q02m/better-email-mcp.git
cd better-email-mcp
bun install
bun run dev

Implantar no Cloudflare

Execute sua própria instância multi-usuário do better-email serverless no Cloudflare (Containers + KV). Cada sub de JWT recebe seu próprio Container Durable Object, e as credenciais de e-mail e tokens OAuth do Outlook de cada usuário são criptografados com AES-256-GCM em um único blob Workers KV por usuário, para que sobrevivam a scale-to-zero / recriação de contêiner sem nova autenticação.

Pré-requisitos: uma conta Cloudflare no plano Workers Paid — necessário para Containers (o nível gratuito do Cloudflare não inclui Containers) — e o CLI wrangler.

git clone https://github.com/n24q02m/better-email-mcp && cd better-email-mcp
wrangler login
Crie o namespace KV (better-email é somente KV — sem D1 / Vectorize):
```
wrangler kv namespace create better-email-kv
```
Cole o id retornado em <better-email-kv-namespace-id> em wrangler.jsonc.

Envie a imagem do contêiner para seu registro gerenciado do Cloudflare (CF Containers não pode puxar de registros externos diretamente), depois defina <YOUR_ACCOUNT_ID> em wrangler.jsonc:

docker pull ghcr.io/n24q02m/better-email-mcp:beta
docker tag ghcr.io/n24q02m/better-email-mcp:beta better-email-mcp:beta
wrangler containers push better-email-mcp:beta   # prints registry.cloudflare.com/<ACCOUNT_ID>/better-email-mcp:beta

Aponte wrangler.jsonc para seu próprio domínio: defina <YOUR_PUBLIC_URL> (ex.: https://email.example.com) e <YOUR_WORKER_DOMAIN> (ex.: email.example.com).
Defina os segredos de implantação:
```
wrangler secret put CREDENTIAL_SECRET      # per-sub vault key + deterministic EdDSA signing (required)
wrangler secret put MCP_RELAY_PASSWORD     # gate for the /authorize setup form
wrangler secret put MCP_DCR_SERVER_SECRET  # proof of an intentional multi-user deploy
```
Substituições opcionais do Outlook — apenas para substituir o cliente público Azure device-code incluído (o padrão não precisa de app Azure do lado do usuário): wrangler secret put OUTLOOK_CLIENT_ID e wrangler secret put OUTLOOK_EMAIL. Para uma organização Microsoft 365, defina também OUTLOOK_TENANT (e OUTLOOK_EXTRA_DOMAINS para caixas de correio no seu próprio domínio).
wrangler deploy, depois abra <YOUR_PUBLIC_URL>/authorize e complete o formulário de relay do navegador.

Os usuários finais fornecem suas próprias credenciais de e-mail — uma App Password via formulário de colagem, ou o login Outlook device-code incluído — através desse formulário de relay; não há EMAIL_CREDENTIALS no lado do servidor. O armazenamento é mapeado para o Cloudflare via MCP_STORAGE_BACKEND=cf-kv (já definido em wrangler.jsonc); veja modo serverless do Cloudflare (somente KV) para os detalhes de criptografia e confiança.

Modelo de Confiança

Este plugin implementa TC-NearZK. A durabilidade do armazenamento depende do modo de implantação; veja o modelo de confiança do mcp-core para a classificação completa.

Modo	Armazenamento	Criptografia	Quem pode ler seus dados?
HTTP remoto (Cloudflare)	Workers KV criptografado `subs/<sub>/config`	AES-256-GCM	Operador do servidor (admin = usuário)
HTTP local Docker	Em memória `Map<sub, CredentialPayload>`	Somente em processo	Processo do servidor (limpo na reinicialização)
stdio	Diretório de configuração platformdirs `mcp` (`config.enc`; ex.: `%APPDATA%\mcp\Config\config.enc` no Windows)	AES-GCM, chave vinculada à máquina	Somente seu usuário do SO (permissão de arquivo 0600)

Licença

Apache-2.0 — Veja LICENSE.