your-mail-mcp

your-mail-mcp

Seu e-mail já contém as respostas: referências de reserva, códigos de portão, faturas, períodos de garantia, promessas que as pessoas fizeram por escrito. Este servidor permite que seu assistente de IA as encontre, e ele só pode ler.

Pergunte coisas como:

• "Encontre a referência de reserva da balsa de junho."
• "Qual era a senha do wifi que o hotel enviou no verão passado?"
• "O que o contador respondeu sobre o IVA, e quando?"
• "Reúna tudo entre mim e o construtor sobre o telhado, em ordem, e resuma quem prometeu o quê."
• "O que chegou esta manhã, em todas as minhas contas, que realmente precisa de mim?"

Use para:

• Busca que entende perguntas. Busca em texto completo em todo o seu histórico, todas as contas em um único índice, formulada do jeito que você pensa.
• Triagem pelo celular. Um resumo matinal do que chegou durante a noite, com o lixo já filtrado, de onde você estiver.
• E-mail como contexto para outros trabalhos. Extraia os requisitos do cliente da conversa e leve-os para sua sessão de codificação ou escrita.
• Agentes que você pode deixar rodando. O processo não tem nenhum caminho que envie, exclua ou mova uma mensagem. Um e-mail malicioso que chega ao seu assistente é lido, e isso é tudo o que pode acontecer com ele. Resumos agendados e agentes sempre ativos são algo tranquilo de executar.

A configuração são dois arquivos e docker compose up -d. Veja Início rápido.

Como funciona

Um servidor MCP auto-hospedado. Ele espelha uma ou mais contas IMAP em um maildir local com mbsync, indexa-os com notmuch e responde a chamadas de ferramentas a partir desse índice. Os aplicativos Claude e ChatGPT conectam-se via HTTPS com OAuth; Claude Code, Codex, Cursor e Claude Desktop conectam-se via stdio na mesma máquina. Qualquer cliente MCP funciona, então, se você quiser privacidade total, pode conectar um apoiado por um LLM local e seu e-mail nunca sai da sua máquina.

O e-mail só se move da esquerda para a direita nessa imagem. O espelho é somente de pull por configuração. A única conexão que o código Go faz com um provedor é um IMAP LIST por conta, para aprender como esse servidor chama suas pastas de lixo e spam; ele nunca seleciona uma caixa de correio e nunca busca uma mensagem. Segurança tem a lista completa do que o processo não pode fazer. A fonte do diagrama é docs/diagrams/how-it-works.html.

Início rápido

Na sua máquina, para a sua máquina. Docker é o único requisito; a imagem em ghcr.io/wildsurfer/your-mail-mcp é construída por CI para amd64 e arm64.

mkdir your-mail && cd your-mail
curl -fsSLO https://raw.githubusercontent.com/wildsurfer/your-mail-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/wildsurfer/your-mail-mcp/main/accounts.example.json -o accounts.json

Coloque suas contas em accounts.json. ${WORK_PASS} é substituído a partir do ambiente, então o arquivo em si não contém senha:

{
  "accounts": [
    { "name": "work", "host": "imap.gmail.com", "user": "you@example.com", "password": "${WORK_PASS}" },
    { "name": "personal", "host": "imap.mail.me.com", "user": "you", "password": "${PERSONAL_PASS}" }
  ]
}

Coloque as senhas em .env ao lado de compose.yaml:

# .env
WORK_PASS=your-gmail-app-password
PERSONAL_PASS=your-icloud-app-specific-password

compose.yaml passa WORK_PASS e PERSONAL_PASS para o contêiner. Uma conta com outro nome de variável precisa que esse nome seja adicionado em environment: lá também.

Dois detalhes do provedor custam mais tempo às pessoas. O Gmail aceita apenas uma senha de aplicativo via IMAP, e senhas de aplicativo precisam da verificação em duas etapas ativada primeiro. O iCloud quer o nome curto antes de @icloud.com como user; o endereço completo falha ao fazer login. Cada chave do arquivo está em a referência.

Esses dois arquivos contêm as senhas do seu e-mail. Mantenha o diretório fora do controle de versão e fora de backups que saiam da máquina.

docker compose up -d
docker compose logs -f     # watch the first sync

O e-mail de HOJE da caixa de entrada fica pesquisável em minutos. O histórico completo segue no ritmo que o provedor permitir, e a ferramenta status informa até onde chegou. Uma conta grande do Gmail leva dias, porque o Google limita downloads IMAP a cerca de 2,5 GB por dia; defina SYNC_TIMEOUT=8h em .env para esse primeiro espelho. Notas do provedor tem os detalhes.

Depois, conecte um cliente. Claude Code:

claude mcp add your-mail -- docker exec -i your-mail-mcp your-mail-mcp stdio

Cursor e VS Code adicionam em um clique, assim que a pilha estiver de pé:

{ "command": "docker", "args": ["exec", "-i", "your-mail-mcp", "your-mail-mcp", "stdio"] }

/plugin marketplace add wildsurfer/your-mail-mcp
/plugin install your-mail@your-mail-mcp

Use pelo celular

Os aplicativos de smartphone Claude e ChatGPT alcançam um conector através dos servidores do fornecedor, então o servidor precisa de um endereço HTTPS público. Um túnel dá um a ele: o túnel faz uma chamada de saída, nada escuta na sua rede doméstica, e o e-mail permanece na sua máquina.

Com Tailscale instalado, um comando, o mesmo no macOS e Linux:

tailscale funnel --bg 8080

Ele imprime um nome de host como https://your-machine.your-tailnet.ts.net, e --bg o mantém em execução entre reinicializações. Coloque esse nome de host em .env junto com uma frase secreta, e então reinicie:

# .env
PUBLIC_URL=https://your-machine.your-tailnet.ts.net
OAUTH_PASSPHRASE=pick-a-long-one-you-can-type-on-a-smartphone

docker compose up -d

OAUTH_PASSPHRASE é a única credencial entre a internet e seu e-mail. Uma suposição errada custa um segundo e as suposições são serializadas, e nenhuma dessas coisas salva uma frase secreta curta. Use uma longa que você ainda consiga digitar em um celular.

O Funnel precisa de certificados HTTPS e do atributo de nó Funnel habilitado para sua tailnet; a CLI oferece adicionar a linha de política na primeira vez. tailscale funnel status mostra o que está exposto, e tailscale funnel --https=443 off o derruba.

Agora adicione o conector. Nem o aplicativo de smartphone Claude nem o ChatGPT podem adicionar um, então você faz isso uma vez na web, e ele então aparece no celular.

1. Em claude.ai ou no Claude Desktop, abra Configurações → Conectores e adicione um conector personalizado.
2. Dê a ele um nome e a URL <PUBLIC_URL>/mcp. Deixe os campos avançados de OAuth vazios; o servidor registra clientes por conta própria.
3. O Claude abre a página de consentimento. Digite seu OAUTH_PASSPHRASE.
4. Abra o aplicativo Claude no seu celular. O conector já está lá; ative-o para uma conversa no menu de ferramentas do compositor.

PUBLIC_URL tem que corresponder exatamente ao que você digita no cliente. O servidor publica PUBLIC_URL + /mcp como o resource em seus metadados OAuth, e uma incompatibilidade lá é o motivo mais comum de um conector se recusar a adicionar.

cloudflared tunnel login
cloudflared tunnel create your-mail

cloudflared tunnel route dns your-mail mail.example.com

tunnel: your-mail
credentials-file: /Users/you/.cloudflared/f9e2….json   # the path create printed
url: http://localhost:8080

cloudflared tunnel run your-mail

claude mcp add --transport http your-mail https://your-host/mcp

codex mcp add your-mail --url https://your-host/mcp
codex mcp login your-mail

Execute em um servidor

Escolha isso quando o espelho deve permanecer ativo independentemente de sua máquina estar ligada. Custa alguns dólares por mês e uma troca real: uma cópia completa em texto simples do seu e-mail vai para um disco alugado, com as senhas de aplicativo ao lado. A instalação é o início rápido mais um túnel, no computador de outra pessoa, e a máquina precisa de endurecimento antes de conter seu e-mail. Ambos estão em docs/server.md.

As ferramentas

Onze ferramentas, todas somente leitura:

search, ids, files e count aceitam uma consulta notmuch (from:, to:, subject:, tag:, folder:, date:2026-01-01..2026-06-30, combinadas com e/ou/não), um account opcional para limitar a uma conta, e podem incluir lixo e spam com include_excluded. Lixo e spam são descobertos por conta via RFC 6154 SPECIAL-USE, então a exclusão funciona quaisquer que sejam os nomes dessas pastas e em qualquer idioma. Enquanto o espelho de uma conta ainda está preenchendo, essas quatro ferramentas adicionam uma nota nomeando a conta e quantas mensagens estão indexadas até agora.

Anexos são listados em show e thread e servidos pela ferramenta attachment uma parte por vez: imagens inline até 5MB, partes textuais como texto marcado, e outros binários como um link assinado de curta duração para GET /attachment/{id}/{part} (um token de portador também funciona lá). Sem um listener HTTP, um binário grande demais é salvo em /index/attachments/ e a ferramenta retorna o caminho para docker cp. Esse diretório é limitado a 1GB; os arquivos mais antigos vão primeiro.

Por que não um dos outros

Existem cerca de quarenta servidores de e-mail MCP no GitHub. Quase todos falam IMAP ao vivo e enviam um caminho de envio, que é o oposto de ambas as escolhas nas quais este servidor se baseia. Dois são próximos o suficiente para nomear.

igor47/notmuchproxy é a coisa mais próxima que já existia, e uma grande parte do motivo de este ter a forma que tem. Ele lê um arquivo notmuch que você mantém atualizado por conta própria, não tem caminho de escrita e aceita um bearer token ou OIDC completo. Sua validação de consulta, que rejeita um prefixo desconhecido com uma explicação, é reimplementada aqui como validateQuery. Duas coisas diferem: ele assume que você já executa mbsync e notmuch, enquanto este servidor gera a configuração do mbsync, sincroniza cada conta em paralelo e descobre lixo e spam via IMAP; e ele não tem o parâmetro account. Se você já tem uma configuração notmuch com a qual está satisfeito, o notmuchproxy é a coisa menor para implantar e você deve usá-lo em vez deste.

hgn/mcp-server-notmuch é apenas stdio, então um cliente em uma máquina, e seu tratamento de conteúdo não confiável é o melhor da pesquisa. O único ponto de estrangulamento render() aqui, que marca cada byte do texto do e-mail em um só lugar para que nenhuma ferramenta individual possa esquecer, vem do render.py dele.

A pesquisa completa, incluindo quais alegações foram lidas no código-fonte e quais foram tiradas de um README, está em docs/research/email-mcp-landscape.md.

Segurança

Leia isto antes de apontá-lo para uma caixa de correio que você valoriza.

Ele não pode escrever. A configuração mbsync gerada para cada conta carrega Sync Pull, Create Near, Remove None e Expunge None (ou, para uma conta com expunge_local definido, Expunge Near, que exclui apenas arquivos locais), e o programa escreve esse arquivo por conta própria, então nada nele pode ser editado para um push. A única operação IMAP no código Go é LIST, emitida por conta na inicialização e a cada hora para encontrar as pastas de lixo e spam; uma conta com exclude_folders definido manualmente pula até isso. O processo não tem caminho que envie, exclua, mova ou marque uma mensagem, e nada nele detém acesso de escrita a qualquer conta.

E-mails excluídos permanecem no espelho. E-mails que você exclui no servidor são mantidos em disco e ocultados da busca pela tag deleted do notmuch. Defina expunge_local: true em uma conta para remover fisicamente essas cópias locais em vez disso. A conta ainda nunca é gravada, mas o espelho então deixa de ser um backup: o que desaparece remotamente desaparece localmente na próxima passada.

O quanto isso é comprovado. Um autor, um operador, três contas reais: uma iCloud e duas Gmail. Nenhuma revisão de segurança de terceiros, e ninguém mais implantou isso. O notmuchproxy tem zero estrelas e uma história de produção mais convincente do que esta.

Senhas são texto simples dentro do contêiner. As senhas das contas vêm do ambiente e são escritas na inicialização em uma configuração mbsync gerada com modo de arquivo 0600. Esse arquivo não é criptografado. Qualquer coisa que possa ler o ambiente do contêiner, ou esse arquivo, pode lê-las. Criptografia de disco, quem pode executar comandos no contêiner e o acesso ao host são responsabilidade do operador; o servidor não faz nenhuma afirmação de criptografar credenciais em repouso.

Uma frase secreta, um consentimento. OAUTH_PASSPHRASE é verificada em tempo constante e protege todo o servidor com um único segredo compartilhado. Não é um sistema de credenciais por usuário, e todos que detêm a frase secreta veem a caixa de correio inteira. Ela não criptografa nada em repouso. Trate-a e as senhas de e-mail com o mesmo cuidado.

Uma caixa de correio é um cofre de segredos. Redefinições de senha, códigos de login e links mágicos chegam todos por e-mail, então apenas o acesso de leitura é suficiente para assumir contas se cair em mãos erradas ou na sessão de IA errada. O design somente leitura e os marcadores de conteúdo não confiável removem o caminho de escrita e o canal de instruções; eles não tornam o conteúdo do e-mail inofensivo. Conecte clientes em que você confia. Fluxos de trabalho de agentes que precisam de suas próprias caixas de entrada precisam de seus próprios endereços, o que é uma ferramenta diferente.

Uma lacuna conhecida. Os resumos de thread do search incluem um nome de exibição para cada mensagem em uma thread correspondente, que o remetente controla. Uma mensagem em uma pasta excluída por padrão (lixo, spam) ainda pode colocar seu próprio nome escolhido pelo atacante diante de você dessa forma, mesmo que seu corpo nunca o faça. thread e show não estão sujeitos a isso. Não está corrigido nesta versão.

Para um servidor que enfrenta a internet, docs/server.md lista as etapas de endurecimento na ordem de quanto cada uma traz de benefício.

Referência

• O arquivo de contas: cada chave, com padrões.
• Variáveis de ambiente: intervalo e tempo limite de sincronização, endereço do listener, INIT_MIRROR.
• Notas do provedor: iCloud, Gmail, Dovecot.
• Solução de problemas: as recusas na inicialização e por que o lixo às vezes não é excluído.
• Sem Docker: binários de lançamento e o que eles chamam externamente.
• Executando em um servidor: script de instalação, endurecimento, seu próprio domínio com Caddy.
• Atualizando da versão 0.3.x.
• Especificação de design e a pesquisa de servidores MCP de e-mail.