Metadata-Version: 2.5
Name: whatsapp-mcp-local
Version: 0.1.2
Summary: MCP server: visão e escrita no WhatsApp nativo do macOS (leitura via banco local read-only + escrita com gate de confirmação)
Project-URL: Homepage, https://github.com/Pl3ntz/whatsapp-mcp
Project-URL: Repository, https://github.com/Pl3ntz/whatsapp-mcp
License: MIT
License-File: LICENSE
Keywords: agent,macos,mcp,model-context-protocol,whatsapp
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.12
Requires-Dist: mcp>=2.0.0
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# whatsapp-mcp

MCP server que dá a agentes IA **visão e escrita** no WhatsApp do macOS — o paralelo do chrome-devtools MCP para o Chrome, aplicado ao app nativo.

- **Ver**: histórico completo (banco local `ChatStorage.sqlite`, read-only), busca, exportação. 834k+ mensagens, offline, sem tocar no app.
- **Escrever**: rascunho pre-preenchido via URL scheme + **Enter com confirmação explícita** (gate). Nada é enviado sem aprovação.
- **Seguro por design**: nunca grava no banco (gravar corrompe o Core Data e não transmite nada), zero protocolo não-oficial (sem Baileys/whatsmeow → sem risco de banimento), dados 100% locais.

## Requisitos

- macOS (com o app WhatsApp nativo instalado e logado)
- Python 3.12+ e [uv](https://docs.astral.sh/uv/)
- Permissão de **Acessibilidade** para o terminal/processo que roda o server (necessária apenas para o Enter do envio; leitura não precisa)

## Instalação

**1 linha (via PyPI):**

```bash
uvx whatsapp-mcp-local
```

**Ou local (desenvolvimento):**

```bash
git clone https://github.com/Pl3ntz/whatsapp-mcp ~/dev/personal/whatsapp-mcp
cd ~/dev/personal/whatsapp-mcp
uv sync
```

## Integração com opencode

Adicione em `~/.config/opencode/opencode.json` (ou `opencode.json` do projeto):

```json
{
  "mcp": {
    "whatsapp": {
      "type": "local",
      "command": ["uvx", "whatsapp-mcp-local"],
      "enabled": true
    }
  }
}
```

Reinicie o opencode. O server anota as tools com `readOnlyHint`/`destructiveHint`, então `send_message` e `confirm_send` **pedem confirmação por padrão** no cliente.

## Integração com Claude Code

```bash
claude mcp add whatsapp-mcp -- uvx whatsapp-mcp-local
```

Ou via `.mcp.json` no projeto:

```json
{
  "mcpServers": {
    "whatsapp-mcp": {
      "command": "uvx",
      "args": ["whatsapp-mcp-local"]
    }
  }
}
```

## Tools

| Tool | Descrição | Flag |
|---|---|---|
| `list_chats` | Lista conversas (nome, não-lidas, última msg) | RO |
| `get_messages` | Lê mensagens de uma conversa (paginável) | RO |
| `search_messages` | Busca texto nas mensagens | RO |
| `get_chat_info` | Metadados da conversa | RO |
| `export_chat` | Exporta histórico para JSON/Markdown | RO |
| `send_message` | Pre-preenche rascunho na conversa (**não envia**) | ⚠️ destrutiva |
| `confirm_send` | Pressiona Enter (envia) — só após aprovação | ⚠️ destrutiva |
| `verify_sent` | Verifica no banco se a mensagem foi enviada | RO |

## Modelo de segurança (importante)

1. **Leitura**: sempre `mode=ro`; o banco nunca é modificado (testes verificam hash antes/depois).
2. **Escrita em 2 passos**: `send_message` só preenche o campo (comportamento do próprio WhatsApp, sem Enter → sem envio). O envio exige `confirm_send` **ou** Enter manual do proprietário.
3. **Nunca** gravar em `ChatStorage.sqlite` / `Axolotl.sqlite` (cripto) — corrompe o app e não transmite ao servidor.
4. JIDs mascarados nos outputs; textos truncados por config.
5. Dados processados localmente; apenas o que o proprietário pedir vai para o modelo.

## Testes

```bash
uv run pytest
```

## Roadmap

- [x] Leitura (list/get/search/export) + escrita com gate — validado E2E
- [x] Annotations MCP (readOnly/destructive) para gate no cliente
- [ ] Driver web (web.whatsapp.com via CDP) como segundo adapter
- [ ] Publicação (PyPI + registro) para instalação `uvx whatsapp-mcp`

## Aviso

Ferramenta para uso pessoal com a própria conta. O schema do banco é do WhatsApp e pode mudar entre versões do app. Não use para enviar mensagens em nome de terceiros ou para fins não autorizados.
