mcp4mail

npx add-mcp 'https://mcp4mail.online/mcp'

mcp4mail

Sua caixa de entrada como um servidor MCP. Conecte uma conta IMAP e deixe seu assistente de IA ler e pesquisar seus e-mails, autorizado via OAuth 2.1. Hospedado em mcp4mail.online, código aberto e auto-hospedável.

Execute você mesmo e suas credenciais nunca saem da sua máquina. Um conector de e-mail hospedado necessariamente mantém sua senha IMAP no servidor de outra pessoa; com o mcp4mail você pode mantê-la no seu próprio banco de dados. Um único docker compose up leva você até lá: veja o guia de auto-hospedagem.

Primeiros passos: o endpoint MCP lista suas contas conectadas; ler e pesquisar e-mails é o próximo passo.

Este projeto é desenvolvido principalmente por desenvolvedores de IA orquestrados através do mcptask.online. Assista ao desenvolvimento acontecer ao vivo: https://mcptask.online/live

Como este projeto é construído

Este é um produto real de código aberto e, ao mesmo tempo, uma demonstração pública. As tarefas são escritas por pessoas no mcptask.online, assumidas por runners (Claude Code dirigido pelo runner mcptask, em nossas próprias máquinas), e cada mudança segue o mesmo caminho: tarefa → branch → pull request → testes e CI → merge → deploy para mcp4mail.online. Ninguém, pessoa ou runner, faz push diretamente para main: o branch é protegido por um conjunto de regras do repositório que exige um pull request aberto, um histórico linear e verificações de status verdes (varreduras de segurança, lint, testes unitários, testes de sistema) antes que um squash merge seja permitido.

Assista ao vivo: https://mcptask.online/live

Onde olhar se você quiser verificar qualquer coisa disso por conta própria: a aba Pull requests, onde cada PR vincula sua tarefa e mostra suas execuções de CI, incluindo as que falharam; CLAUDE.md e .claude/, as instruções com as quais os runners trabalham; e a configuração de CI.

As pessoas ainda escrevem os resumos das tarefas, revisam os pull requests e decidem o que vai ao ar e o que não vai; um runner executa uma tarefa de ponta a ponta, mas não decide o que construir. Um runner é um usuário com um assento aqui, não algo gratuito ou ilimitado.

Ferramentas MCP

Ferramenta	O que faz
list_mail_accounts	Lista as contas de e-mail que você conectou, com os ids que as outras ferramentas aceitam.
get_mail_account	Mostra os detalhes de conexão de uma conta (nunca sua senha).
list_folders	Lista as pastas de uma conta.
search_messages	Pesquisa por assunto, remetente, destinatários, nomes de anexos e data.
get_message	Lê uma mensagem.
get_attachment	Baixa um anexo de uma mensagem: um link de curta duração, ou com inline: true o próprio arquivo (até 5 MB) dentro da resposta MCP.
search_contacts	Encontra endereços com os quais você se correspondeu.
get_outgoing_status	Informa se um e-mail entregue a send_message foi enviado.
set_flags	Marca uma mensagem ou a marca como lida / não lida. Escrita.
move_message	Move uma mensagem para outra pasta. Escrita.
trash_message	Move uma mensagem para a Lixeira. Escrita.
create_folder	Cria uma pasta. Escrita.
create_draft	Salva um rascunho. Escrita.
send_message	Prepara um e-mail; ele só é enviado após sua aprovação. Escrita.

As ferramentas de escrita funcionam apenas em uma caixa de entrada cujo proprietário ativou "Permitir que a IA faça alterações nesta caixa de entrada" e marcou o que a ferramenta faz; em todos os outros lugares elas são recusadas, veja abaixo. send_message nunca envia por conta própria: você recebe um e-mail com um link e a mensagem só sai quando você pressiona Enviar.

Auto-hospedagem

cp .env.example .env    # fill in the values
docker compose up -d

Leia docs/self-hosting.md primeiro: quais variáveis de ambiente importam, por que HITCH_RESOURCE_URI deve corresponder exatamente à sua URL pública, TLS e como as senhas da caixa de entrada são armazenadas.

Stack

Ruby 3.4, Rails 8.1, PostgreSQL, Hotwire (Turbo + Stimulus), Tailwind CSS, Solid Queue / Cache / Cable.

Desenvolvimento

bin/setup   # install gems, prepare the database, start the dev server
bin/dev     # web server + Tailwind watcher
bin/ci      # rubocop, security audits, tests, system tests

O PostgreSQL deve estar rodando localmente; a configuração padrão conecta via socket local como seu usuário do sistema operacional.

Segredos

Este repositório é público. Nada secreto é jamais commitado: config/master.key, .env* e credentials.yml são ignorados pelo git, segredos de produção vêm do ambiente.

As senhas da caixa de entrada são criptografadas em repouso com Active Record Encryption. Em produção, gere chaves com bin/rails db:encryption:init e forneça-as através das credenciais criptografadas (active_record_encryption.*) ou das variáveis de ambiente ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY, ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY e ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT. Desenvolvimento e teste derivam chaves descartáveis do tmp/local_secret.txt específico da máquina.

Contas de e-mail

O mcp4mail conecta-se à sua caixa de entrada via IMAP simples com nome de usuário e senha. Use uma senha específica de aplicativo sempre que seu provedor oferecer uma (Gmail, iCloud, Fastmail, Outlook.com, Yahoo e outros oferecem), para que o que é armazenado no banco de dados possa ser revogado por conta própria e não seja a chave para toda a sua conta. O Gmail é suportado da mesma forma: ative a verificação em duas etapas e entre com uma senha de aplicativo. Em uma conta do Google Workspace, o administrador pode desativar IMAP ou senhas de aplicativo, e somente ele pode reativá-las. Como a senha é armazenada e quem pode descriptografá-la é descrito nas notas de segurança do guia de auto-hospedagem.

Endpoint MCP: somente leitura por design

Cada caixa de entrada é somente leitura até que você diga o contrário. Cada caixa de entrada na página de Contas de e-mail tem um interruptor, "Permitir que a IA faça alterações nesta caixa de entrada", e ele está desligado por padrão.

• Desligado (o padrão): a IA só pode ler e pesquisar. Qualquer ferramenta que alteraria a caixa de entrada é recusada com uma mensagem informando ao modelo que a caixa de entrada é somente leitura, e a recusa é registrada no log de auditoria como denied.
• Ligado: caixas de seleção se desdobram sob o interruptor e você marca o que a IA pode fazer nessa caixa de entrada: marcar como lida e sinalizar (set_flags), mover mensagens e criar pastas (move_message, create_folder), escrever rascunhos (create_draft), enviar e responder, sempre após sua aprovação (send_message), excluir para a lixeira (trash_message). Todas estão marcadas quando você liga o interruptor. Uma ferramenta cuja caixa não está marcada é recusada da mesma forma que em uma caixa de entrada somente leitura. list_mail_accounts e get_mail_account informam ao modelo o que ele pode fazer.

O registro de ferramentas se recusa a iniciar com uma ferramenta que não seja somente leitura e não destrutiva nem explicitamente declarada como ferramenta de escrita (write_tool destructive: ..., permission: ... em McpTools::ApplicationTool, onde permission é uma das caixas de seleção acima), então nada pode entrar como ferramenta de escrita por acidente. As ferramentas de escrita anunciam readOnlyHint: false e declaram seu próprio destructiveHint.

O que somente leitura significa e não significa, claramente:

• Nada pode alterar uma caixa de entrada sem seu interruptor e a caixa de seleção correspondente. As pastas são abertas com IMAP EXAMINE, então até mesmo a leitura não marca mensagens como vistas.

• Ela lê seus e-mails, sempre que um cliente de IA que você conectou solicitar. Conecte apenas clientes em que você confia para isso.

• Ela mantém uma cópia dos cabeçalhos das mensagens (remetente, destinatários, assunto, data, sinalizações, tamanho) em seu próprio banco de dados, atualizada a cada 15 minutos, para que as pesquisas não atinjam seu servidor de e-mail a cada vez.

• Escopo. Cada ferramenta resolve dados através das próprias contas de e-mail do usuário conectado; um id de conta que não seja dele é recusado antes que qualquer código da ferramenta seja executado.

• Limites de taxa. Hitch limita cada par usuário + cliente (120 solicitações por minuto); além disso, cada usuário tem uma cota para chamadas de ferramentas em todos os seus clientes (240 por minuto).

• Log de auditoria. Cada chamada é registrada em mcp_audit_events: usuário, cliente, ferramenta, conta, resultado, linhas retornadas, duração. Argumentos não são armazenados.

• Proteção de pesquisa. As páginas são limitadas a 50 resultados, e cada conta tem um orçamento de pesquisas (60 por 10 minutos) e linhas retornadas (1.000 por hora), para que um loop descontrolado não possa percorrer uma caixa de entrada inteira.

Contribuindo

Veja CONTRIBUTING.md. bin/ci deve passar.

Licença

MIT