Apple Mail MCP

Apple Mail MCP

O único servidor Apple Mail MCP com busca de corpo com cobertura total — confiável em caixas de entrada grandes, onde servidores baseados em AppleScript expiram. 8 ferramentas para ler, buscar e extrair conteúdo de e-mails.

Leia a documentação para o guia completo.

Início Rápido

Claude Code (plugin)

claude plugin marketplace add imdinu/apple-mail-mcp
claude plugin install apple-mail@imdinu

Claude Desktop (pacote de um clique)

Baixe o apple-mail-mcp-<version>.mcpb do último lançamento e clique duas vezes nele.

Tanto o plugin quanto o pacote executam o pacote PyPI publicado por meio de um lançador leve (uvx → pipx → venv privado, o que estiver disponível) — sem código embutido, comportamento idêntico a uma instalação manual. Eles iniciam o servidor com --watch; conceda Acesso Total ao Disco ao aplicativo de inicialização (Claude Code / Claude Desktop) para que o índice permaneça atualizado.

Qualquer cliente MCP

pipx install apple-mail-mcp

Adicione ao seu cliente MCP:

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

Construir o Índice de Busca (Recomendado)

# Requires Full Disk Access for Terminal
# System Settings → Privacy & Security → Full Disk Access → Add Terminal

apple-mail-mcp index --verbose

Configurar (Opcional)

apple-mail-mcp init   # writes ~/.apple-mail-mcp/config.toml

Grava um arquivo de configuração comentado que você pode editar para definir padrões como sua conta principal ou caixa de entrada. Cada chave tem uma variável de ambiente APPLE_MAIL_* correspondente se você preferir configuração baseada em ambiente. Consulte Configuração para o esquema completo e as regras de precedência.

Ferramentas

Ferramenta	Finalidade
list_accounts()	Listar contas de e-mail
list_mailboxes(account?)	Listar caixas de entrada
get_emails(filter?, limit?)	Obter e-mails — todos, não lidos, sinalizados, hoje, últimos_7_dias
get_email(message_id)	Obter um único e-mail com conteúdo completo + anexos
search(query, scope?, before?, after?, highlight?)	Buscar — todos, assunto, remetente, corpo, anexos
get_email_links(message_id)	Extrair links de um e-mail
get_email_attachment(message_id, filename)	Extrair conteúdo de anexos
get_attachment(message_id, filename)	Obsoleto — use get_email_attachment()

Desempenho

Testado contra 6 outros servidores Apple Mail MCP em uma caixa de entrada real de ~73 mil mensagens:

• Único servidor com busca de corpo com cobertura total. A maioria dos concorrentes não suporta busca de corpo; o que suporta (BastianZim) faz varredura ao vivo apenas das 5000 mensagens mais recentes — falha silenciosa em qualquer coisa mais antiga. Nosso índice FTS5 cobre toda a caixa de entrada.
• ~3ms para buscar um único e-mail via leitura .emlx com prioridade em disco (sem ida e volta JXA).
• ~1ms para list_accounts e ~5ms para listar 50 e-mails via leituras diretas do SQLite do Índice de Envelopes (0.4+) — mesmo caminho usado por BastianZim/rusty/pl-lyfx, com JXA como fallback de correção.
• ~7ms para busca por assunto via FTS5 — competitivo com Rust nativo na mesma operação.
• Confiável em todas as 6 operações avaliadas em uma caixa de entrada de 73 mil mensagens; servidores baseados em AppleScript expiram, geram erros de sintaxe ou pulam operações que não suportam.

Configuração

O Apple Mail MCP funciona imediatamente. Para personalizar padrões, execute apple-mail-mcp init para gerar um modelo config.toml — ou use as variáveis de ambiente APPLE_MAIL_* correspondentes. Consulte a documentação de Configuração para o esquema completo e a precedência CLI > env > arquivo > padrão.

Substituições de ambiente por cliente via configuração de inicialização do cliente MCP também funcionam:

{
  "mcpServers": {
    "mail": {
      "command": "apple-mail-mcp",
      "args": ["--watch"],
      "env": {
        "APPLE_MAIL_DEFAULT_ACCOUNT": "Work"
      }
    }
  }
}

Uso via CLI

Todas as ferramentas também estão disponíveis como comandos CLI independentes (sem necessidade de servidor MCP):

apple-mail-mcp search "quarterly report" --scope subject
apple-mail-mcp search "invoice" --after 2026-01-01 --limit 10
apple-mail-mcp read 12345
apple-mail-mcp emails --filter unread --limit 10
apple-mail-mcp accounts
apple-mail-mcp mailboxes --account Work
apple-mail-mcp extract 12345 invoice.pdf

Todos os comandos geram saída JSON. Gere uma habilidade Claude Code para acesso via CLI:

apple-mail-mcp integrate claude > ~/.claude/skills/apple-mail.md

Desenvolvimento

git clone https://github.com/imdinu/apple-mail-mcp
cd apple-mail-mcp
uv sync
uv run ruff check src/
uv run pytest

Licença

GPL-3.0-or-later