Apple Mail

---

✨ O que você pode fazer

🔍 Faça perguntas à sua caixa de entrada. "O que o Stefan me enviou sobre o memorando na semana passada?" A busca roda na velocidade do banco de dados — remetente, caixa de entrada, datas, não lidos, anexos — e reconstrói conversas inteiras.

🕳️ Encontre o que o próprio Mail não consegue. A busca integrada do Mail só lê a primeira linha da maioria das mensagens. O apple-mail-mcp indexa o corpo de cada mensagem no seu Mac — e, para contas do Exchange, ele até busca os corpos que o Mail nunca baixou, direto da sua própria caixa de entrada no servidor. Consultas que retornavam nada retornam vinte.

🎭 Envie como o "você" certo. E-mail de trabalho pela via do trabalho, pessoal pelo Gmail — um parâmetro escolhe a identidade. Cada mensagem é composta do zero como e-mail limpo e em conformidade com padrões, que renderiza em qualquer lugar, inclusive no Outlook (o caminho de composição via AppleScript que chega em branco no Outlook é o motivo deste projeto existir).

⏰ Agende como "Enviar Depois", mas com script. Uma mensagem agendada é congelada por completo — anexos, identidade, texto exato. O Exchange pode executá-la no servidor no horário solicitado, com a tampa fechada; outros provedores usam um remetente local em segundo plano e entregam na próxima passada (ou logo após o Mac acordar).

🗂️ Trie em escala, sem medo. "Arquive estes 40 boletins" vira um plano revisável: nada é movido até ser aprovado, cada mensagem é re-verificada antes de ser tocada e o resultado é confirmado contra os registros do próprio Mail depois. Excluir significa a Lixeira do Mail — nada é jamais apagado.

📝 Rascunhe onde seus rascunhos vivem. Componha na sua pasta real de Rascunhos do Exchange, pronta para abrir no Outlook ou OWA — criada, nunca enviada automaticamente.

⚡ Por que é diferente

Todos os outros MCPs do Apple Mail usam AppleScript tanto para encontrar quanto para agir. Este não usa — e isso se nota:

Operação	AppleScript whose-clause	apple-mailbox-mcp
🔍 Buscar 300 mil mensagens	segundos até timeout	milissegundos
🎯 Endereçar uma mensagem em uma caixa de 71 mil	7–10 s (medido)	< 0,1 ms
✉️ Enviar e-mail	corpo renderiza em branco no Outlook	renderiza em qualquer lugar, texto simples+HTML
⏰ Agendar e-mail	—	no servidor no Exchange; fila local confiável em qualquer outro lugar
🗂️ Triagem em massa	uma chamada por mensagem, fire-and-forget	um plano revisado, uma aplicação, verificado

Cada número acima foi medido em um armazenamento real de ~300.000 mensagens; o script e o método completo estão em docs/benchmarks.md.

Se os benchmarks se confirmarem na sua caixa de entrada, uma ⭐ ajuda outros a encontrar isto.

🛡️ Feito para ser confiável

• ✅ Plano → revisão → aplicação → verificação. Ações em massa são congeladas em um plano que você pode ler antes de qualquer coisa acontecer; o resultado é confirmado contra o armazenamento do próprio Mail depois — nunca presumido.
• 🗑️ Nada é jamais apagado. "Excluir" arquiva na Lixeira do Mail, e planos destrutivos têm sua própria porta separada e limitada.
• 👓 Modo de e-mail somente leitura. Defina EMAIL_MCP_READ_ONLY=1 e apenas as 11 ferramentas de e-mail não mutáveis existem na sessão. A busca ainda pode manter seu índice local de corpos, e a recuperação de anexos grava o arquivo solicitado no diretório temporário configurado.
• 💾 Fila de agendamento à prova de falhas. Atualizações de manifesto são descarregadas e substituídas atomicamente, então uma reescrita interrompida mantém o último registro válido. Se um arquivo for danificado independentemente, o diagnóstico o nomeia em vez de afirmar que a fila está vazia, enquanto mensagens agendadas saudáveis continuam se movendo.
• 🧾 Um registro de atividades local e de melhor esforço. Envios, agendamentos, cancelamentos e execuções de triagem são registrados sem que um log não gravável bloqueie o e-mail. Para reconciliação, a própria mensagem, seu Message-ID e seu registro agendado permanecem autoritativos.
• 🔒 Sem relay de e-mail de terceiros. O conteúdo do e-mail permanece local, exceto por e-mails que você envia e acesso opcional ao seu próprio provedor para preenchimento de corpos do Exchange/IMAP, rascunhos e agendamento no servidor. Senhas SMTP permanecem no Chaveiro do macOS ou no 1Password; tokens OAuth da Microsoft vivem em um cache privado 0600 sob ~/.email-mcp/graph/.
• 📜 Um contrato escrito. Desde a v1.0, as formas, códigos de erro e limites de cada ferramenta evoluem aditivamente, mantidos por mais de 800 testes automatizados.
• 🤝 Claro para qualquer cliente MCP. Todas as 21 ferramentas identificam o que fazem, explicam cada entrada e declaram se leem, alteram ou podem remover dados. Clientes mais novos recebem resultados estruturados; clientes mais antigos mantêm o mesmo texto JSON. Tanto a linha mantida MCP 1.x quanto a atual MCP 2.x são testadas.
• 🧱 Feito para evoluir sem quebrar seu fluxo de trabalho. Regras de e-mail são isoladas do MCP, do Mail.app, do Exchange, da entrega e do armazenamento local. Mudanças de provedor ou SDK ficam na borda enquanto o contrato de 21 ferramentas permanece estável. As regras de dependência são aplicadas no CI e explicadas no guia de arquitetura.
• 📦 Versões que você pode verificar. Cada versão marcada é construída e instalada em um ambiente limpo antes da publicação. O GitHub inclui o wheel, o arquivo-fonte, somas SHA-256 e proveniência de build assinada — não apenas o código-fonte.
• 🩺 Autodiagnóstico. apple-mail-mcp status fornece uma tela legível de prontidão, agendamento e recuperação. apple-mail-mcp doctor fornece o detalhe diagnóstico completo e uma correção exata para qualquer coisa em vermelho.

🚀 Início rápido

1. Conceda Acesso Total ao Disco ao seu aplicativo de terminal (Ajustes do Sistema → Privacidade e Segurança → Acesso Total ao Disco) e depois saia e reabra o terminal. Este é o único ajuste manual da Apple — não há pop-up para isso.

2. Instale e configure:

   uvx apple-mailbox-mcp setup     # or: pipx install apple-mailbox-mcp
   # or via Homebrew:
   brew install parasxos/tap/apple-mail-mcp && apple-mail-mcp setup
   

3. Registre com seu cliente — uma linha para o Claude Code:

   claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mailbox-mcp
   

   ou o mesmo bloco JSON para Claude Desktop / Cursor / VS Code (claude_desktop_config.json / .cursor/mcp.json / .vscode/mcp.json):

   {
     "mcpServers": {
       "apple-mail": { "command": "uvx", "args": ["apple-mailbox-mcp"] }
     }
   }
   

4. Verifique: uvx apple-mailbox-mcp status imprime uma tela de prontidão — ou apenas peça ao seu cliente para executar a ferramenta doctor; cada linha vermelha vem com sua correção exata. A primeira construção do índice de corpos em uma caixa grande roda em segundo plano e pode levar alguns minutos; a busca funciona imediatamente e é concluída conforme o índice é preenchido.

Antes de executar setup, conceda ao seu aplicativo de terminal Acesso Total ao Disco (Ajustes do Sistema → Privacidade e Segurança → Acesso Total ao Disco) — é assim que a leitura permanece rápida e local. Não há pop-up para este; é o único ajuste manual da Apple, e setup o leva ao painel exato se detectar que está faltando.

setup pergunta tudo em palavras simples (Enter vazio aceita a resposta recomendada), oferece uma identidade de envio, constrói o índice de busca de corpos, verifica se a atualização noturna realmente roda e termina imprimindo o único bloco que você cola no seu cliente MCP:

{
  "mcpServers": {
    "apple-mail": { "command": "apple-mail-mcp" }
  }
}

A configuração termina com um veredito claro de pronto ou etapas numeradas de recuperação. Conceda Automação → Mail quando a triagem pedir pela primeira vez. Verifique a instalação, a próxima mensagem agendada e envios agendados com falha a qualquer momento com apple-mail-mcp status; use apple-mail-mcp doctor para o detalhe técnico completo.

💡 Novo no terminal? Três coisas que parecem erradas e não são: brew install pipx quer um y digitado (Enter sozinho é rejeitado); pipx ensurepath pode imprimir um ⚠️ — a linha "pipx está pronto!" depois dele é o veredito; e após ensurepath, feche e reabra o terminal uma vez para que apple-mail-mcp seja encontrado.

🔌 Funciona com

Cada cliente abaixo fala MCP via stdio; o comando é sempre uvx apple-mailbox-mcp.

Claude Code

claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mailbox-mcp

Claude Desktop

Adicione em ~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "apple-mail": { "command": "uvx", "args": ["apple-mailbox-mcp"] } } }

Cursor

Adicione o mesmo bloco em ~/.cursor/mcp.json (ou por projeto em .cursor/mcp.json).

VS Code (Copilot MCP)

Adicione o mesmo bloco sob "servers" em .vscode/mcp.json.

Codex CLI

# ~/.codex/config.toml
[mcp_servers.apple-mail]
command = "uvx"
args = ["apple-mailbox-mcp"]

Qualquer cliente MCP stdio

Aponte para uvx apple-mailbox-mcp. O contrato de comunicação é apenas aditivo desde a v1.0.

🔧 Solução de problemas

Sintoma	Correção
O cliente diz que o servidor falhou ao iniciar, mas uvx apple-mailbox-mcp funciona no seu terminal	Aplicativos GUI não herdam o PATH do seu shell. Use o caminho absoluto: "command": "/opt/homebrew/bin/uvx" (encontre o seu com which uvx).
database is locked ou resultados vazios	Falta Acesso Total ao Disco para o aplicativo que inicia o servidor (o cliente, não o terminal). Conceda e depois saia e reabra completamente esse aplicativo.
A busca encontra e-mails recentes, mas não corpos de e-mails antigos	O índice de corpos ainda está sendo construído — a primeira construção em uma caixa de 100 mil+ leva minutos. status mostra o progresso.
O envio falha com transport_unavailable	Execute doctor: ele nomeia a via com falha (item do Chaveiro ausente, socket SSH frio, host SMTP inacessível) e imprime a correção exata.
A triagem não faz nada na primeira vez	Conceda Automação → Mail quando o macOS pedir; o prompt aparece no primeiro uso, não na instalação.

🧰 As 21 ferramentas

Grupo	Ferramentas
🔍 Leitura (8)	search_emails (busca de corpo completo) · get_email · get_emails_batch · get_thread · list_mailboxes · list_recent · get_attachment · refresh_mail
✉️ Envio (6)	send_email · reply_email (em thread, com citação) · create_draft · schedule_email · list_scheduled · cancel_scheduled
🗂️ Triagem (5)	triage_plan · triage_plan_delete · triage_apply · mailbox_create · mailbox_delete
🩺 Meta (2)	doctor (diagnóstico completo com strings de correção) · audit (o registro local)

Anexos nos dois sentidos, com orçamento de tamanho. Respostas são encadeadas corretamente em qualquer cliente. O agendamento sobrevive ao sono — uma mensagem com vencimento enquanto a tampa estava fechada sai no primeiro tick após o despertar, ou exatamente no horário via Exchange.

🎭 Seus endereços, suas vias

O endereço De: decide como o e-mail viaja. ~/.email-mcp/identities.toml:

default = "work"

[work]                    # sent through a host you already trust, over SSH
from_addr = "you@example.org"
driver    = "ssh_sendmail"
host      = "bastion.example.org"   # any login host you already SSH to

[gmail]                   # classic SMTP — the app password stays in 1Password
from_addr = "you@gmail.com"
driver    = "smtp"
host      = "smtp.gmail.com"
op        = "op://Personal/gmail app password/password"

Identidades do Exchange podem adicionar um único login para desbloquear os extras: rascunhos arquivados na sua pasta real de Rascunhos e envios agendados executados pelo próprio servidor — tampa fechada, Mac dormindo. setup oferece isso em uma única pergunta simples. A leitura não precisa de nenhuma configuração de envio.

---