Email MCP for Gmail, iCloud and microsoft

Organize, marque, leia, exclua e limpe e-mails com IA.

GitHub
22
Experimente este MCPPatrocinado

Documentação

@marlinjai/email-mcp

email-mcp logo

Um servidor MCP unificado para acesso a e-mail em Gmail, Outlook, iCloud e provedores IMAP genéricos.

Recursos

  • Suporte a múltiplos provedores — Gmail (API REST), Outlook (Microsoft Graph), iCloud (IMAP) e IMAP/SMTP genéricos
  • Autenticação OAuth2 — Fluxos OAuth baseados em navegador para Gmail e Outlook, com renovação automática de tokens
  • Cliente de e-mail completo — Pesquisar, ler, enviar, responder, encaminhar, organizar e gerenciar rascunhos
  • Operações em lote — Excluir, mover ou marcar centenas de e-mails em uma única chamada
  • Pesquisa leve — Resultados de pesquisa compactos por padrão (~20KB vs ~1.4MB) com recuperação opcional do corpo completo
  • Armazenamento criptografado de credenciais — Criptografia AES-256-GCM em repouso com chaves derivadas da máquina
  • APIs nativas do provedor — Usa a API do Gmail e o Microsoft Graph quando disponíveis para recursos mais ricos, com fallback para IMAP para compatibilidade universal

Instalação

Instale globalmente a partir do npm:

npm install -g @marlinjai/email-mcp

Ou execute diretamente com npx (sem necessidade de instalação):

npx @marlinjai/email-mcp

Início Rápido

  1. Execute o assistente de configuração interativo para adicionar suas contas de e-mail:
npx -y -p @marlinjai/email-mcp@latest email-mcp-setup

A flag -p/--package é obrigatória. Este pacote declara dois binários (email-mcp para o servidor MCP, email-mcp-setup para este assistente). Sem -p, o npx executa o binário que corresponde ao nome do próprio pacote (email-mcp, o servidor) e passa silenciosamente email-mcp-setup para ele como um argumento ignorado — o servidor então fica aguardando entrada de protocolo MCP no stdin para sempre, sem produzir nenhuma saída. Parece exatamente um travamento. -p diz explicitamente ao npx qual pacote resolver e qual de seus binários executar de fato.

O assistente guiará você pela seleção do provedor e autenticação. Após cada conta, ele pergunta se você deseja adicionar outra — para que você possa configurar Gmail, Outlook e iCloud de uma só vez.

  1. Adicione o servidor à sua configuração MCP (.mcp.json):
{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["@marlinjai/email-mcp"]
    }
  }
}
  1. Comece a usar as ferramentas de e-mail no Claude Code — pesquise sua caixa de entrada, envie e-mails, organize mensagens e muito mais.

Guias de Configuração do Provedor

Gmail

Nenhuma configuração necessária — o assistente de configuração cuida de tudo usando credenciais OAuth integradas (PKCE):

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
# Select "Gmail" when prompted
# Choose "Full" or "Restricted" permission scope when asked
# A browser window opens for Google authorization
# Grant the requested permissions and return to the terminal

O assistente pergunta qual escopo de permissão do Gmail autorizar:

  • Completo (padrão) — tudo abaixo, mais exclusão permanente imediata que ignora a Lixeira (https://mail.google.com/, o escopo de permissão máxima do Gmail).
  • Restrito — ler, enviar, rotular, arquivar e mover para a Lixeira (gmail.modify + gmail.settings.basic), mas sem exclusão permanente. Todas as ferramentas deste servidor funcionam de forma idêntica no modo Restrito, exceto uma exclusão explícita com permanent: true, que falha com um erro da API do Gmail em vez de ter sucesso.

Passe --scope full ou --scope restricted para pular o prompt, ou defina EMAIL_MCP_GMAIL_SCOPE=restricted no ambiente em que o assistente é executado.

Nota: Se você preferir usar seu próprio aplicativo OAuth em vez do compartilhado que este pacote inclui, crie um Cliente OAuth 2.0 para Desktop no Google Cloud Console com a API do Gmail habilitada e, em seguida, defina EMAIL_MCP_GMAIL_CLIENT_ID e EMAIL_MCP_GMAIL_CLIENT_SECRET no ambiente antes de executar o assistente de configuração (e no ambiente do servidor MCP, já que a reautenticação usa as mesmas variáveis). Isso dá a você seu próprio ciclo de vida de tokens, independente do projeto Cloud do publicador, e contorna o aviso de aplicativo não verificado do Google e o limite de 100 usuários de teste para suas próprias contas, uma vez que você se adicione como usuário de teste no seu próprio aplicativo.

Outlook

Nenhuma configuração necessária — o assistente de configuração cuida de tudo usando credenciais OAuth integradas (PKCE):

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
# Select "Outlook" when prompted
# A browser window opens for Microsoft authorization
# Sign in and grant the requested permissions

Nota: Se você preferir usar seu próprio aplicativo OAuth, registre um no Azure Portal com permissões Mail.ReadWrite, Mail.Send, MailboxSettings.ReadWrite (necessárias para email_create_block_rule) e offline_access, e então defina EMAIL_MCP_OUTLOOK_CLIENT_ID no ambiente antes de executar o assistente de configuração.

iCloud

  1. Acesse appleid.apple.com e faça login.
  2. Navegue até Senhas Específicas do App e gere uma nova senha.
  3. Execute o assistente de configuração:
npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
# Select "iCloud" when prompted
# Enter your iCloud email address
# Enter the app-specific password you generated

IMAP Genérico

Execute o assistente de configuração com os detalhes do seu servidor IMAP/SMTP:

npx -y -p @marlinjai/email-mcp@latest email-mcp-setup
# Select "Other IMAP" when prompted
# Enter your IMAP host, port, and credentials
# Optionally enter SMTP host and port for sending

Ferramentas Disponíveis (32)

Gerenciamento de Contas (4)

FerramentaDescrição
email_list_accountsLista todas as contas configuradas com status de conexão
email_add_accountAdiciona uma nova conta IMAP ou iCloud (Gmail/Outlook exigem o assistente de configuração)
email_remove_accountRemove uma conta e suas credenciais armazenadas; revoga a concessão do Google para Gmail, remove os tokens do Outlook do cache local de tokens e relata o resultado
email_test_accountTesta a conexão com uma conta

Leitura e Pesquisa (6)

FerramentaDescrição
email_list_foldersLista todas as pastas/rótulos de uma conta
email_searchPesquisa e-mails com filtros. Retorna resultados compactos por padrão (returnBody=false). Defina returnBody=true para incluir corpos completos de e-mail
email_getObtém o conteúdo completo do e-mail por ID (cabeçalhos, corpo, metadados de anexos)
email_get_threadObtém uma thread/conversa de e-mail inteira
email_get_attachmentBaixa um anexo específico por ID (retorna dados em base64)
email_save_attachmentBaixa um anexo diretamente para o disco, retornando apenas metadados — evita o custo de tokens de enviar arquivos grandes como base64. outputPath é relativo a um diretório fixo de downloads (~/.email-mcp/downloads, substituível com EMAIL_MCP_DOWNLOADS_DIR) e não pode escapar dele

Envio e Rascunhos (6)

FerramentaDescrição
email_sendCompõe e envia um novo e-mail (para, cc, bcc, assunto, corpo)
email_replyResponde a um e-mail (suporta responder a todos, preserva o encadeamento)
email_forwardEncaminha um e-mail para novos destinatários
email_draft_createSalva um rascunho sem enviar
email_draft_updateAtualiza um rascunho existente no lugar. No Gmail/Outlook, o ID do rascunho permanece inalterado; no iCloud/IMAP genérico não há atualização no lugar (mensagens IMAP são imutáveis), então o rascunho antigo é excluído e um novo é anexado — o ID retornado é um novo ID, sempre use-o daqui em diante
email_draft_listLista todos os rascunhos

Organização (8)

FerramentaDescrição
email_moveMove um e-mail para uma pasta diferente. Suporta sourceFolder para IMAP/iCloud
email_transferMove ou copia e-mails entre contas, preservando a mensagem original (remetente, data, encadeamento) via transferência MIME bruta. deleteAfter=true envia o original para a Lixeira somente após uma importação confirmada (movimentação segura entre contas)
email_deleteExclui um e-mail (Lixeira ou permanente). Suporta sourceFolder para IMAP/iCloud
email_markMarca como lido/não lido, com estrela ou sinalizado. Suporta sourceFolder para IMAP/iCloud
email_labelAdiciona/remove rótulos (somente Gmail)
email_folder_createCria uma nova pasta
email_get_labelsLista todos os rótulos com contagens (somente Gmail)
email_get_categoriesLista todas as categorias (somente Outlook)

Operações em Lote (3)

FerramentaDescrição
email_batch_deleteExclui vários e-mails de uma vez (até 1000 para Gmail, lotes de 20 para Outlook, intervalos de UID para IMAP)
email_batch_moveMove vários e-mails para uma pasta em uma única chamada
email_batch_markMarca vários e-mails como lido/não lido, com estrela ou sinalizado de uma vez

Todas as ferramentas em lote aceitam um parâmetro sourceFolder para IMAP/iCloud e incluem um fallback sequencial para máxima compatibilidade.

Moderação de Spam (5)

FerramentaDescrição
email_report_spamReporta um e-mail como spam/lixo, treinando o filtro do próprio provedor — o mesmo sinal que o botão "Reportar Lixo" envia no Gmail/Outlook. Isso é diferente de email_delete, que remove a mensagem mas não ensina nada ao filtro. Não é um relatório de abuso para a equipe de segurança do provedor; apenas treina o filtro desta conta
email_batch_report_spamReporta vários e-mails como spam/lixo de uma vez
email_create_block_ruleCria uma regra permanente que intercepta e-mails futuros que correspondam a um padrão (domínio/endereço do remetente, assunto ou conteúdo arbitrário de cabeçalho) e os exclui ou move. Use headerContains (por exemplo, um domínio de Reply-To) para bloquear uma família de modelos de spam cujo domínio visível de "De" rotaciona — corresponder ao domínio rotativo diretamente para de funcionar em poucos dias. Não suportado no iCloud/IMAP genérico (não existe um mecanismo padrão de regras no servidor entre servidores IMAP). No Outlook, moveToJunk arquiva diretamente na pasta Lixo Eletrônico e exige o escopo MailboxSettings.ReadWrite. No Gmail, moveToJunk pula a caixa de entrada (arquiva) em vez de literalmente arquivar em Spam — a API de filtros do Gmail rejeita o rótulo SPAM em regras permanentes (apenas o próprio classificador do Gmail pode aplicá-lo; email_report_spam ainda pode, pois é uma ação direta por mensagem, não um filtro) — e exige o escopo gmail.settings.basic. Contas autenticadas antes da existência desses escopos precisam executar o assistente de configuração novamente uma vez para reconsentir
email_list_block_rulesLista as regras de bloqueio permanentes de uma conta, para auditoria ou antes de excluir uma
email_delete_block_ruleExclui uma regra de bloqueio permanente — use para desfazer uma regra que se mostrou ampla demais

Somente Gmail e Outlook para as ferramentas de regras; email_report_spam/email_batch_report_spam funcionam em todos os provedores (iCloud/IMAP recorrem a um movimento de melhor esforço para a pasta do tipo Lixo da conta, sem sinal de treinamento de ML do fornecedor, já que IMAP genérico não tem nada para treinar).

Uso com Claude Code

Adicione o seguinte ao seu arquivo .mcp.json (no nível do projeto ou global ~/.claude/.mcp.json):

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["@marlinjai/email-mcp"]
    }
  }
}

Uma vez configurado, você pode pedir ao Claude para interagir com seu e-mail:

  • "Verifique minha caixa de entrada para mensagens não lidas"
  • "Pesquise e-mails de alice@example.com na última semana"
  • "Responda ao e-mail mais recente do Bob e agradeça a ele"
  • "Mova todos os boletins informativos para a pasta Arquivo"
  • "Exclua todos os e-mails de spam" (usa operações em lote para velocidade)
  • "Rascunhe um e-mail de acompanhamento para a equipe sobre a reunião"

Desenvolvimento

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in development mode (watch for changes)
pnpm dev

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run integration tests (requires real email accounts)
pnpm test:integration

Armazenamento de Credenciais

As credenciais da conta são criptografadas em repouso com AES-256-GCM em ~/.email-mcp/credentials.enc.

Por padrão, a chave de criptografia é derivada de um identificador estável e específico da máquina (o UUID de hardware no macOS, /etc/machine-id no Linux ou o MachineGuid no Windows), com fallback para o nome do host quando nenhum está disponível.

Defina a variável de ambiente EMAIL_MCP_KEY para fornecer sua própria senha. Isso é recomendado quando o identificador da máquina pode mudar (por exemplo, em contêineres ou CI), ou quando você deseja mover credentials.enc entre máquinas:

export EMAIL_MCP_KEY="your-strong-passphrase"

Quando EMAIL_MCP_KEY está definido, os arquivos de credenciais existentes são transparentemente re-criptografados com a senha na próxima vez que forem lidos.

O token de atualização do Outlook reside no cache de tokens da biblioteca de autenticação da Microsoft (MSAL), ~/.email-mcp/msal-cache.enc, criptografado com o mesmo esquema e derivação de chave que credentials.enc, então EMAIL_MCP_KEY protege ambos os arquivos. Versões anteriores a 1.8.0 mantinham esse cache como JSON simples em ~/.email-mcp/msal-cache.json; a versão 1.8.0 o criptografa e exclui o arquivo simples na primeira vez que o lê, sem desconectar você. Voltar para uma versão mais antiga depois significa entrar no Outlook novamente.

No macOS e Linux, anexos salvos com email_save_attachment são gravados somente para o proprietário (0600), e as pastas que o email-mcp cria para eles são 0700. Eles não são criptografados.

O callback de login OAuth iniciado por email-mcp-setup escuta apenas nos endereços de loopback (127.0.0.1, e ::1 quando disponível), então nada mais na sua rede pode alcançá-lo.

Suporte

Se este projeto for útil para você, considere apoiar seu desenvolvimento:

Licença

MIT