MCP WPPConnect Server

Um servidor MCP (Model Context Protocol) que expõe operações do WhatsApp via protocolo padronizado para integração com Claude Desktop e outros clientes MCP.

🚀 Visão Geral

Este servidor permite que você:

• Gerencie sessões do WhatsApp (inicializar, verificar status, QR codes, fechar)

• Envie mensagens de texto

• Gerencie participantes de grupos e comunidades

• Obtenha listas de contatos e chats

Além disso, o servidor é compatível com qualquer cliente MCP, permitindo integração com diversos agentes de IA além do Claude Desktop.

📋 Pré-requisitos

• Node.js 18+

• npm ou yarn

• Uma conta do WhatsApp para autenticação

🔧 Instalação

🏃‍♂️ Uso Rápido

Desenvolvimento

Produção

🤖 Integração com Claude Desktop e Outros Agentes MCP

Este servidor segue o padrão Model Context Protocol (MCP) e pode ser integrado com qualquer cliente MCP compatível. Além do Claude Desktop, suportamos diversos agentes de IA.

🎯 Clientes MCP Suportados

📁 Arquivos de Configuração Prontos

Todas as configurações estão disponíveis no diretório mcp-configs/:

🔧 Configuração Rápida para Qualquer Agente

1. Localize o arquivo de configuração do seu agente

2. Copie a configuração apropriada:

   { "mcpServers": { "whatsapp-mcp": { "command": "node", "args": ["/caminho/completo/para/mcp-wppconnect-server/build/index.js"], "env": { "NODE_ENV": "production", "MAX_SESSIONS": "10", "QR_EXPIRY_MINUTES": "5" } } } }

3. Reinicie seu agente

4. Teste a integração:

   "Inicialize uma sessão WhatsApp com ID meu-teste"

🤖 OpenAI Codex CLI

💎 Google Gemini CLI

📝 Anthropic Claude

🔧 Agente Genérico

📋 Testando a Integração

Use nosso script de teste para verificar tudo está funcionando:

🛠️ Configuração Automática

Execute nosso configurador automático:

🎯 Dicas de Uso

1. Sempre use IDs únicos para cada sessão

2. Aguarde o QR code antes de escanear

3. Teste comandos simples primeiro

4. Verifique logs em caso de erro

5. Use números válidos com código do país

📚 Recursos Adicionais

• Documentação de Configurações

• Guia de Deploy

• Solução de Problemas

• Exemplos de Uso

Configure o Claude Desktop para usar o servidor MCP:

1. Preparação

2. Localize o arquivo de configuração do Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

3. Configure o arquivo de configuração

Para Desenvolvimento (usando npm run dev):

Para Produção (usando build):

4. Validação da Configuração

5. Reinicie o Claude Desktop

• Feche completamente o Claude Desktop

• Aguarde 5 segundos

• Abra novamente

• Verifique os logs do Claude Desktop para confirmar a conexão

6. Teste de Integração

No Claude Desktop, você deve conseguir:

• Inicializar uma sessão WhatsApp

• Verificar o status da sessão

• Enviar mensagens

• Gerenciar grupos e comunidades

7. Troubleshooting da Integração

Se encontrar problemas:

1. Verifique os logs do servidor:

2. Verifique os logs do Claude Desktop:

• Geralmente localizados em ~/Library/Logs/Claude/ (macOS)

3. Teste manualmente:

4. Problemas comuns:

   • Caminho incorreto: Use caminho absoluto completo

   • Permissões: Certifique-se de que o arquivo é executável

   • Dependências faltando: Execute npm install novamente

   • Build quebrado: Execute npm run build novamente

8. Configuração Avançada

Para ambientes de produção, considere:

📚 Ferramentas Disponíveis

Gerenciamento de Sessão

• initialize_session - Inicializa uma nova sessão WhatsApp

• get_qr_snapshot - Obtém QR code para autenticação

• get_session_status - Verifica status da sessão

• close_session - Fecha sessão ativa

Mensagens

• send_text - Envia mensagem de texto

Grupos

• promote_group_participant - Promove participante a admin

• demote_group_participant - Remove privilégios de admin

Comunidades

• get_community_participants - Lista participantes da comunidade

• promote_community_participant - Promove participante da comunidade

• demote_community_participant - Remove privilégios de participante da comunidade

Utilidades

• get_contacts - Lista todos os contatos

• get_chats - Lista todas as conversas

📝 Exemplos de Uso

Inicializar uma sessão

Enviar uma mensagem

Obter participantes de um grupo

⚙️ Configuração

Variáveis de Ambiente

🚨 Solução de Problemas

Servidor não inicia

• Verifique se Node.js 18+ está instalado

• Confirme que todas as dependências foram instaladas

• Verifique as permissões de arquivo

QR code não aparece

• Certifique-se de que a sessão foi inicializada corretamente

• Verifique o status da sessão

• O QR code expira em 5 minutos - reinicie se necessário

Erros de autenticação

• Verifique se o número do WhatsApp está correto

• Certifique-se de que a sessão está autenticada

• Tente fechar e reinicializar a sessão

🔒 Segurança

• Nunca exponha tokens ou informações sensíveis

• Use HTTPS para comunicações externas

• Implemente rate limiting em produção

• Monitore atividades suspeitas

🤝 Contribuindo

1. Faça fork do projeto

2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)

3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')

4. Push para a branch (git push origin feature/AmazingFeature)

5. Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🙏 Agradecimentos

• WPPConnect Team pelo excelente trabalho com a biblioteca WPPConnect

• Model Context Protocol pela especificação MCP

📞 Suporte

Para problemas e dúvidas:

• Abra uma issue no GitHub

• Consulte o guia TROUBLESHOOTING.md

• Verifique a documentação em src/tools/README.md