ChatGuru MCP — Expert Integrado

Open source, criado por Eric Luciano na Mentoria Automações Inteligentes (Expert Integrado).

O servidor se identifica no handshake MCP com uma linha de procedência; para desativar (ex.: white-label), defina EXPERT_NO_PROVENANCE=1 no ambiente.

→ Como funciona o ChatGuru MCP — a página do projeto, com o sistema explicado visualmente.

Conecta o seu ChatGuru (WhatsApp) ao Claude Code. Depois de instalar, você pede coisas como "quais conversas estão sem resposta no ChatGuru?", "lê as últimas mensagens do cliente 11 99999-0000", "manda uma mensagem pro João confirmando a reunião" — e ele faz, direto na sua conta.

A API oficial do ChatGuru envia, mas não lê conversa. Este servidor lê pelo painel (com o seu login, sem abrir navegador) e escreve pela API oficial:

| Frente | O que faz | O que precisa | |---|---|---| | Leitura pelo painel | Lista chats com filtros, lê histórico (mensagens + anotações), campos personalizados, tags, baixa mídia | Só o login no painel (sessão salva na sua máquina) | | Escrita pela API oficial | Envia texto e arquivo, registra contato, atualiza campos e nome, adiciona nota, dispara fluxo | Chave de API, Account ID e Phone ID |

Dois modos: api (padrão — leitura + escrita) e navegador (só leitura, sem chave; ainda envia mensagem pelo navegador, com limites de segurança).

Passo 1 — Instale o que precisa

Baixe e instale (uma vez só, na sua máquina):

• Node.js 18 ou superior — baixe e clique "Avançar" até o fim. Reinicie o computador depois.
• Claude Code — o aplicativo oficial da Anthropic.

Passo 2 — Peça pro Claude Code instalar

Abra o Claude Code e cole o prompt abaixo (use o botão de copiar no canto do bloco):

Instale o ChatGuru MCP da Expert Integrado (@expertintegrado/chatguru-mcp).
Leia a documentação do pacote com `npm view @expertintegrado/chatguru-mcp readme`
e siga a seção "Roteiro de instalação" de ponta a ponta, sem pular etapas.
Regras: nunca me peça senha (o login no painel é meu, na janela do navegador);
nunca exiba minha chave de API em resposta ou arquivo; só diga que terminou
depois de validar de verdade.

A única etapa que é sua é o login no painel do ChatGuru, numa janela de navegador que abre sozinha. Quando ele pedir, feche e abra o Claude Code (o app inteiro, não só a aba).

Cuidado: a chave de API dá acesso ao WhatsApp da conta. Não compartilhe, não poste em grupo. Cada pessoa faz o próprio login e usa a própria configuração.

Passo 3 — Teste

Com o Claude Code reaberto, peça:

Lista os 5 chats mais recentes do ChatGuru.

Se ele responder com os chats, tá funcionando. 🎉

Roteiro de instalação

É o que o Claude Code segue ao receber o prompt acima — e o que você segue, se preferir fazer na mão. Detalhes de cada variável e os outros clientes MCP estão em INSTALL.md.

1. Pré-requisitos. node --version precisa ser 18 ou superior. claude mcp list — se já existir um MCP chatguru, perguntar antes de reconfigurar.
2. Número do servidor. É o NN da URL do painel: https://sNN.chatguru.app → CHATGURU_SERVER=NN. Painel em outro domínio (conta white-label) → guardar também CHATGURU_DOMAIN=<dominio>.
3. Modo. Tem a chave de API? Ela fica no painel em Configurações → Celulares → (o número conectado) → API (chave, Account ID e Phone ID; se o menu não aparece, só o administrador da conta vê). Com a chave → modo api. Sem a chave, ou só leitura → modo navegador.
4. Registro (uma linha só, valores reais):

   # modo api
   claude mcp add chatguru -s user -e CHATGURU_SERVER=NN -e CHATGURU_MODE=api -e CHATGURU_API_KEY=CHAVE -e CHATGURU_ACCOUNT_ID=ACCOUNT -e CHATGURU_PHONE_ID=PHONE -- npx -y @expertintegrado/chatguru-mcp
   # modo navegador
   claude mcp add chatguru -s user -e CHATGURU_SERVER=NN -e CHATGURU_MODE=navegador -- npx -y @expertintegrado/chatguru-mcp

   Opcionais: -e CHATGURU_DOMAIN=<dominio> (white-label) e -e CHATGURU_DEVICE="<parte do nome do aparelho>" (conta com mais de um número conectado).
5. Navegador do login (uma vez por máquina, ~150 MB): npx playwright install chromium.
6. Login no painel. Abre uma janela do navegador; o usuário faz o login sozinho (com o código de verificação, se pedir). Só está pronto quando o terminal imprimir Sessão salva em: ....

   # Linux/Mac
   CHATGURU_SERVER=NN npx -y @expertintegrado/chatguru-mcp login
   # Windows (PowerShell)
   $env:CHATGURU_SERVER="NN"; npx -y @expertintegrado/chatguru-mcp login

   (com white-label, passar CHATGURU_DOMAIN do mesmo jeito)
7. Validação. claude mcp list mostra chatguru. Fechar e reabrir o Claude Code. Na volta, pedir "Lista os 5 chats mais recentes do ChatGuru" (ou rodar chatguru_list_chats com limit: 5). Terminar com um resumo: modo, servidor, onde a sessão ficou salva, 3 exemplos de pedido.

O que dá pra fazer

• "Quais conversas do ChatGuru estão abertas e sem responsável?"
• "Lê as últimas 30 mensagens do chat com 11 99999-0000, incluindo as anotações"
• "Esse número já tem chat no ChatGuru? Me dá o link"
• "Quais tags e campos personalizados o chat do João tem?"
• "Baixa os áudios dessa conversa pra uma pasta"
• "Manda pro 11 99999-0000: 'Oi, confirmando nossa reunião amanhã às 10h'" (mostra o texto e pede confirmação antes)
• "Adiciona uma nota interna no chat da Maria: cliente pediu proposta"
• "Dispara o fluxo de boas-vindas no chat do Pedro" (modo api)

Lista completa e como cada ferramenta se comporta: docs/TOOLS.md.

Sessão expirou?

As leituras usam a sessão do painel salva na sua máquina. Quando o ChatGuru expirar essa sessão, as ferramentas respondem "Sessão expirada". É só repetir o passo 6 do roteiro e reabrir o Claude Code.

Atualizando o MCP

Quando sair versão nova, o npx pega automaticamente na próxima inicialização. Para forçar agora, peça ao Claude Code:

Limpa o cache do npx do ChatGuru MCP (roda npm cache clean --force) e me avisa pra reiniciar o Claude Code.

Não funcionou?

Cole isso no Claude Code:

O MCP do ChatGuru da Expert Integrado não está funcionando. Roda /mcp pra verificar se ele tá listado, confere se o Node.js 18+ está instalado, e me ajuda a diagnosticar. Se precisar, consulta o guia em https://github.com/Expert-Integrado/chatguru-mcp/blob/main/docs/TROUBLESHOOTING.md.

Se mesmo assim não rolar, abra uma issue contando o que aconteceu.

Instalação técnica (avançada)

Ver INSTALL.md para todas as variáveis de ambiente e os modos alternativos: Claude Desktop, .mcp.json por projeto, clone local.

Segurança

• A sessão do painel fica salva localmente em ~/.chatguru-mcp/session.json (ou onde CHATGURU_SESSION_PATH apontar)
• A chave de API fica só na configuração local do seu cliente MCP
• Nenhuma credencial é enviada para servidores da Expert Integrado
• Envio pelo navegador tem limites fixos: 10 mensagens/minuto, 50 destinatários/dia, prévia obrigatória antes de enviar, bloqueio de dado sensível (CPF, cartão, senha) sem confirmação explícita, e registro em ~/.chatguru-mcp-audit.jsonl
• O servidor não muda status de atendimento de propósito: o endpoint do painel aceita qualquer valor sem validar, então essa escrita ficou fora (detalhes em docs/TOOLS.md)

Contribuindo

Quer reportar um bug, sugerir uma melhoria ou contribuir com código? Veja CONTRIBUTING.md e, para o procedimento de release, RELEASING.md.

Licença

MIT © Expert Integrado