# vistoazul-mcp

> Servidor **MCP** (Model Context Protocol) da **[Visto Azul](https://vistoazul.com.br)**. Dê ao **Claude**, **Claude Code**, **Cursor** e a qualquer cliente MCP a capacidade de operar o **WhatsApp**: enviar texto, mídia e **cobrança PIX**, disparar campanhas, gerenciar contatos e configurar webhooks — tudo pela API REST do Visto Azul, sem taxa por mensagem da Meta e com anti-ban de fábrica.

## O que é

O MCP é o padrão que conecta agentes de IA a ferramentas externas. Com este servidor, você pede em linguagem natural — *"manda um PIX de R$97 pro cliente"*, *"dispara a campanha pra essa lista"* — e o agente executa pela sua conta do Visto Azul.

## Ferramentas

| Ferramenta | O que faz |
|---|---|
| `list_instances` | Lista os números conectados e o status |
| `send_text` | Envia mensagem de texto |
| `send_media` | Envia imagem, vídeo ou documento |
| `send_pix` | Envia cobrança PIX na conversa |
| `send_poll` | Envia enquete |
| `check_numbers` | Verifica quem tem WhatsApp (anti-ban) |
| `create_campaign` | Cria campanha (disparo em massa) |
| `campaign_status` | Status de uma campanha |
| `list_contacts` | Lista contatos (filtra por tag) |
| `upsert_contact` | Cria ou atualiza um contato |
| `set_webhook` | Configura webhook para receber mensagens |
| `download_media` | Baixa a mídia recebida (base64) e transcreve áudio |
| `mark_read` | Marca mensagem como lida (tique azul) |
| `send_presence` | Envia "digitando…" / "gravando áudio" |
| `react_message` | Reage a uma mensagem com emoji |
| `edit_message` | Edita uma mensagem enviada |
| `delete_message` | Apaga uma mensagem para todos |

## Instalação

Você precisa de uma **API key** do Visto Azul: crie a conta em [dashboard.vistoazul.com.br](https://dashboard.vistoazul.com.br), conecte seu número e copie a key em *Instâncias*.

### Claude Code

```bash
claude mcp add vistoazul -e VISTOAZUL_API_KEY=SUA_API_KEY -- npx -y vistoazul-mcp
```

### Claude Desktop / Cursor (config JSON)

```json
{
  "mcpServers": {
    "vistoazul": {
      "command": "npx",
      "args": ["-y", "vistoazul-mcp"],
      "env": { "VISTOAZUL_API_KEY": "SUA_API_KEY" }
    }
  }
}
```

## Configuração

| Variável | Obrigatória | Padrão |
|---|---|---|
| `VISTOAZUL_API_KEY` | sim | — |
| `VISTOAZUL_BASE_URL` | não | `https://dashboard.vistoazul.com.br/api/v1` |

## Links

- 🌐 Site: **https://vistoazul.com.br**
- 📚 Documentação: **https://vistoazul.com.br/docs**
- 🧩 Node do n8n: **https://www.npmjs.com/package/n8n-nodes-vistoazul**

## Licença

[MIT](./LICENSE)