mcp-chatwoot

MCP server para Chatwoot — lista conversas, lê mensagens, busca, envia respostas e transcreve áudios automaticamente.

Funciona em qualquer client MCP: Claude Code, Cursor, VS Code (Cline/Continue/Copilot), Windsurf, Antigravity, Zed.

Dois transportes: stdio (default, recomendado) e HTTP (com bearer token opcional pra expor pra rede).

Tools

| Tool | Descrição | |---|---| | list_conversations | Lista conversas (filtros: status, page, labels, inbox_id). | | read_conversation_messages | Mensagens de uma conversa com texto, autor, timestamp, anexos e transcrição de áudios. | | search_messages | Busca full-text em mensagens. | | summarize_conversation | Resumo: participantes, contagem por autor, primeira/última mensagem, áudios transcritos. | | send_message | Envia mensagem pública ou nota privada numa conversa. Requer CHATWOOT_WRITE_TOKEN. |

Features

Evolution API fallback

Se a instância Evolution API estiver configurada, o MCP complementa automaticamente as mensagens do Chatwoot com mensagens que ainda não foram sincronizadas — buscando pelo número de telefone do contato. Dedup por timestamp (janela de 5 s).

Transcrição de áudio (Groq Whisper)

Com GROQ_API_KEY configurado, todos os áudios das conversas são transcritos automaticamente em paralelo via Groq Whisper (whisper-large-v3, idioma pt). Funciona tanto com áudios do Chatwoot (URL) quanto do Evolution (base64).

Variáveis de ambiente

| Var | Obrigatório | Default | Descrição | |---|---|---|---| | CHATWOOT_URL | sim | http://localhost:3000 | URL do Chatwoot. | | CHATWOOT_TOKEN | sim | — | API access token (Perfil → Access Token). | | CHATWOOT_ACCOUNT_ID | não | 1 | ID da conta. | | CHATWOOT_INBOX_ID | não | — | Trava o MCP em um inbox. Vazio = toda a conta. | | CHATWOOT_INBOX_LABEL | não | — | Label descritivo do inbox (só documentação, ex: "Techmax WhatsApp"). | | CHATWOOT_WRITE_TOKEN | não | — | Token com permissão de escrita. Ativa a tool send_message. | | GROQ_API_KEY | não | — | Ativa transcrição automática de áudios via Groq Whisper. | | EVOLUTION_URL | não | — | URL da Evolution API (ex: http://localhost:8080). | | EVOLUTION_APIKEY | não | — | API key da Evolution. | | EVOLUTION_INSTANCE | não | — | Nome da instância Evolution. | | MCP_TRANSPORT | não | stdio | stdio ou http. | | PORT | não | 8765 | Porta HTTP (se MCP_TRANSPORT=http). | | MCP_AUTH_TOKEN | não | — | Se setado, exige Authorization: Bearer <token> (só HTTP). |

Instalação

Claude Code

claude mcp add chatwoot \
  -e CHATWOOT_URL=https://seu-chatwoot.com \
  -e CHATWOOT_TOKEN=SEU_TOKEN \
  -e CHATWOOT_INBOX_ID=2 \
  -- npx -y mcp-chatwoot

Com Evolution + transcrição:

claude mcp add chatwoot \
  -e CHATWOOT_URL=https://seu-chatwoot.com \
  -e CHATWOOT_TOKEN=SEU_TOKEN \
  -e CHATWOOT_WRITE_TOKEN=SEU_WRITE_TOKEN \
  -e CHATWOOT_INBOX_ID=2 \
  -e GROQ_API_KEY=SEU_GROQ_KEY \
  -e EVOLUTION_URL=http://localhost:8080 \
  -e EVOLUTION_APIKEY=SEU_EV_KEY \
  -e EVOLUTION_INSTANCE=minha-instancia \
  -- npx -y mcp-chatwoot

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "chatwoot": {
      "command": "npx",
      "args": ["-y", "mcp-chatwoot"],
      "env": {
        "CHATWOOT_URL": "https://seu-chatwoot.com",
        "CHATWOOT_TOKEN": "SEU_TOKEN",
        "CHATWOOT_INBOX_ID": "2"
      }
    }
  }
}

VS Code (Cline, Continue, Copilot)

.vscode/mcp.json:

{
  "servers": {
    "chatwoot": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-chatwoot"],
      "env": {
        "CHATWOOT_URL": "https://seu-chatwoot.com",
        "CHATWOOT_TOKEN": "SEU_TOKEN"
      }
    }
  }
}

Windsurf / Antigravity / Zed

Mesma config de stdio do Cursor — adapte o arquivo de config do client.

Docker (HTTP transport)

docker run -d \
  --name mcp-chatwoot \
  -p 8765:8765 \
  -e MCP_TRANSPORT=http \
  -e MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
  -e CHATWOOT_URL=https://seu-chatwoot.com \
  -e CHATWOOT_TOKEN=SEU_TOKEN \
  -e CHATWOOT_INBOX_ID=2 \
  ghcr.io/REPLACE_ME/mcp-chatwoot:latest

Depois no client (Claude Code):

claude mcp add --transport http chatwoot http://SERVER:8765/mcp \
  --header "Authorization: Bearer SEU_MCP_AUTH_TOKEN"

Rodar local sem instalar

git clone <repo>
cd mcp-chatwoot
npm install
npm run build
CHATWOOT_URL=... CHATWOOT_TOKEN=... node dist/index.js

Licença

MIT