ZapMCP

Dá ao Claude, ao Codex e a outros assistentes compatíveis com MCP acesso de leitura ao WhatsApp Desktop do Mac: conversas, imagens, documentos e áudios transcritos. O ZapMCP roda no próprio Mac, não se conecta aos servidores do WhatsApp e nunca altera a pasta do WhatsApp.

A instalação abaixo é a do Claude Desktop, o caminho mais completo e testado. Para outros assistentes, veja Outros assistentes.

O que dá para pedir

• "O que ficou combinado no grupo da obra esta semana?"

• "Resuma os áudios que a Ana me mandou ontem."

• "Ache a mensagem em que falaram do orçamento de março e leia o PDF que veio junto."

• "Quem pediu para remarcar a reunião, e para quando?"

O assistente escolhe as ferramentas: lista as conversas, lê as mensagens de um período, busca por palavras, abre imagens e documentos e transcreve áudios.

Related MCP server: WhatsApp MCP Server

Como funciona

WhatsApp Desktop ──cópia──▶ indexador ──▶ índice local ◀── servidor MCP ◀── Claude, Codex…

1. O ZapMCP copia o banco de dados local do WhatsApp e monta um índice próprio, com busca.

2. Um servidor MCP oferece ao assistente ferramentas para consultar esse índice.

3. Os áudios são transcritos no Mac com whisper.cpp.

Só leitura: o ZapMCP não envia mensagens.

Requisitos

• Mac com Apple Silicon (M1 ou mais novo). Em Mac com Intel não foi testado: a biblioteca de transcrição não tem versão pronta para Intel.

• WhatsApp Desktop, o app nativo, com a conta conectada.

• Claude Desktop, ou outro assistente com suporte a MCP.

• uv e Node.js, pelo Homebrew: brew install uv node. O Homebrew também instala as ferramentas de linha de comando da Apple, usadas para compilar o lançador.

Instalação

São três passos. O terceiro, liberar o acesso, só é feito na primeira instalação, e sem ele o macOS fica pedindo permissão.

1. Baixar e empacotar

git clone https://github.com/pedrosoutom/zapmcp.git
cd zapmcp
make

O make compila o lançador do ZapMCP (um programa pequeno, em launcher/), gera dist/ZapMCP.mcpb e mostra os próximos passos.

2. Instalar no Claude Desktop

open dist/ZapMCP.mcpb

O Claude Desktop abre a tela da extensão: clique em Instalar. Outro jeito é arrastar o arquivo para Ajustes > Extensões. Nos ajustes da extensão dá para ligar ou desligar a transcrição automática.

3. Liberar o acesso uma vez só

A pasta do WhatsApp é protegida pelo macOS. Sem permissão, o macOS pergunta de tempos em tempos se o zapmcp pode "acessar dados de outros apps", e o "Permitir" vale só por um tempo. Para não ser mais perguntado, dê Acesso Total ao Disco ao lançador do ZapMCP, o arquivo zapmcp que veio na extensão. Ele é quem inicia o servidor, então a permissão fica só com o ZapMCP, e não com o uv ou com o Claude.

make acesso

O comando abre o painel Ajustes do Sistema > Privacidade e Segurança > Acesso Total ao Disco e uma janela do Finder com o arquivo zapmcp selecionado. Arraste o arquivo para a lista, confira se a chave ficou ligada e confirme com sua senha ou o Touch ID. Às vezes o item não aparece na lista, mas a permissão vale mesmo assim.

Sem o make: no painel, clique em +, aperte Cmd+Shift+G, cole o caminho abaixo e ligue a chave.

~/Library/Application Support/Claude/Claude Extensions/local.mcpb.pedro-souto.zapmcp/bin/zapmcp

Se você pular este passo, o ZapMCP percebe e o Claude avisa na conversa como liberar. Deu certo quando o macOS para de perguntar e o aviso não aparece mais.

Primeiro uso

Peça algo ao Claude sobre suas conversas. Na primeira vez:

• o Claude Desktop pede para você aprovar as ferramentas do ZapMCP;

• o uv baixa o Python e as dependências, então a primeira resposta demora mais;

• se o acesso ainda não foi liberado, o macOS pergunta se o zapmcp pode acessar dados de outros apps (clique em Permitir) e o Claude explica como liberar de vez;

• o ZapMCP monta o índice (cerca de 10 segundos num M1) e passa a atualizá-lo a cada 5 minutos;

• se a transcrição estiver ligada, o modelo de transcrição (0,6 GB) é baixado uma vez do Hugging Face. Depois, os áudios dos últimos 7 dias e cada áudio novo são transcritos em segundo plano, enquanto o Claude está aberto. Grupos arquivados ficam de fora e, na bateria, só são transcritos os áudios que o Claude pede.

Atualizar

git pull
make

Instale o novo dist/ZapMCP.mcpb no Claude Desktop e clique em atualizar. A permissão continua valendo, a menos que o lançador tenha mudado (launcher/zapmcp.c). Nesse caso, libere de novo.

Quando sai uma versão nova, o assistente avisa na conversa, no máximo uma vez por dia, com o link das novidades. O aviso pode ser desligado nos ajustes da extensão ("Avisar sobre versões novas").

Outros assistentes (Codex, Cursor e outros)

O ZapMCP é um servidor MCP padrão, que roda no Mac e conversa pela entrada e saída do processo (stdio). Qualquer assistente que aceite servidores MCP locais pode usá-lo com este comando:

/opt/homebrew/bin/uv --directory /caminho/para/zapmcp run zapmcp serve

Ele foi testado com um cliente MCP genérico; com o Codex, ainda não. No Codex, a configuração fica em ~/.codex/config.toml, que vale para o Codex no terminal, na extensão do editor e no app:

[mcp_servers.zapmcp]
command = "/opt/homebrew/bin/uv"
args = ["--directory", "/caminho/para/zapmcp", "run", "zapmcp", "serve"]
startup_timeout_sec = 60
tool_timeout_sec = 120

Os tempos maiores que o padrão evitam que o Codex desista: na primeira vez, o servidor instala as dependências e monta o índice antes de responder, e transcribe_audio espera até 90 segundos.

O que muda fora do Claude Desktop:

• O macOS cobra o acesso do app que roda o assistente: o app de terminal, para quem usa o Codex no terminal, ou o próprio app, nos assistentes de desktop. O Acesso Total ao Disco vai para esse app e vale para tudo o que ele rodar. O lançador só faz diferença no Claude Desktop.

• Os ajustes da extensão viram variáveis de ambiente, como ZAPMCP_TRANSCRIBE=0. A lista está no guia de uso.

• Nem todo assistente mostra as imagens que o view_images devolve. Não testamos fora do Claude.

• Para atualizar, basta git pull na pasta do ZapMCP e reiniciar o assistente.

Privacidade

• O ZapMCP lê uma cópia do banco do WhatsApp e guarda o índice, as transcrições e o modelo em ~/Library/Application Support/zapmcp. Essa pasta não é criptografada.

• Os áudios são transcritos no Mac e não saem dele.

• O que as ferramentas devolvem ao assistente (mensagens, transcrições, imagens, documentos) entra na conversa com ele, como qualquer texto que você cola nela.

• Uma vez por dia, o ZapMCP pergunta ao GitHub qual é a última versão. A consulta revela ao GitHub só o seu endereço IP e a versão instalada, e pode ser desligada nos ajustes da extensão.

Desinstalar

1. Remova a extensão em Ajustes > Extensões no Claude Desktop.

2. Apague os dados do ZapMCP: rm -rf ~/Library/Application\ Support/zapmcp.

3. Se o zapmcp aparecer na lista de Acesso Total ao Disco, remova-o.

Problemas comuns

Para usar no Claude Code ou pelo terminal, ajustar a transcrição e conhecer os limites, veja o guia de uso.

Avisos

• O ZapMCP lê um banco interno do WhatsApp, sem documentação. Uma atualização do app pode quebrar a leitura.

• Projeto independente, sem relação com o WhatsApp ou a Meta.

Licença

MIT