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

# Clone o repositório git clone <url-do-repositório> cd mcp-wppconnect-server # Instale as dependências npm install # Compile o projeto npm run build

🏃‍♂️ Uso Rápido

Desenvolvimento

npm run dev

Produção

npm run build npm start

🤖 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

Cliente	Status	Configuração
Claude Desktop	✅ Oficial	`claude_desktop_config.json`
OpenAI Codex CLI	✅ Testado	`mcp-codex-config.json`
Google Gemini CLI	✅ Testado	`mcp-gemini-config.json`
Cline	✅ Compatível	`mcp-generic-config.json`
Roo Code	✅ Compatível	`mcp-generic-config.json`
Outros clientes MCP	✅ Genérico	`mcp-generic-config.json`

📁 Arquivos de Configuração Prontos

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

# Ver todas as configurações disponíveis ls mcp-configs/*.json # Usar o configurador automático ./setup-mcp-agents.sh

🔧 Configuração Rápida para Qualquer Agente

Localize o arquivo de configuração do seu agente
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" } } } }
Reinicie seu agente
Teste a integração:
"Inicialize uma sessão WhatsApp com ID meu-teste"

🤖 OpenAI Codex CLI

# Inicializar sessão codex 'Inicialize uma sessão WhatsApp com ID codex-teste' # Enviar mensagem codex 'Envie uma mensagem para +551234567890 dizendo Olá do Codex' # Verificar status codex 'Verifique o status da sessão codex-teste'

💎 Google Gemini CLI

# Criar sessão gemini-cli 'Crie uma sessão WhatsApp com ID gemini-teste' # Listar contatos gemini-cli 'Liste todos os meus contatos WhatsApp' # Obter QR code gemini-cli 'Obtenha o QR code da sessão gemini-teste'

📝 Anthropic Claude

# Inicializar sessão claude 'Inicialize uma sessão WhatsApp com ID claude-teste' # Obter QR code claude 'Obtenha o QR code da sessão claude-teste' # Enviar mensagem claude 'Envie mensagem para +551234567890 com Olá do Claude'

🔧 Agente Genérico

# Comandos genéricos funcionam com qualquer cliente MCP [seu-agente] 'Inicialize uma sessão WhatsApp com ID generico-teste' [seu-agente] 'Envie mensagem para +551234567890 com Olá' [seu-agente] 'Liste meus grupos do WhatsApp'

📋 Testando a Integração

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

# Executar testes completos ./test-mcp-agents.sh # Verificar se servidor está rodando ./test-mcp-quick.sh

🛠️ Configuração Automática

Execute nosso configurador automático:

# Configurar para todos os agentes ./setup-mcp-agents.sh # Configurar para um agente específico ./setup-mcp-agents.sh codex

🎯 Dicas de Uso

Sempre use IDs únicos para cada sessão
Aguarde o QR code antes de escanear
Teste comandos simples primeiro
Verifique logs em caso de erro
Use números válidos com código do país

📚 Recursos Adicionais

Configure o Claude Desktop para usar o servidor MCP:

1. Preparação

# Certifique-se de que o build foi executado com sucesso npm run build # Teste o servidor antes de configurar npm start # Você deve ver: "MCP WPPConnect Server connected and ready for requests"

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):

{ "mcpServers": { "mcp-wppconnect-server": { "command": "npm", "args": ["run", "dev"], "cwd": "/Users/jeff/Desktop/MCP CONNECT" } } }

Para Produção (usando build):

{ "mcpServers": { "mcp-wppconnect-server": { "command": "node", "args": ["/Users/jeff/Desktop/MCP CONNECT/build/index.js"] } } }

4. Validação da Configuração

# Verifique se o arquivo de configuração é válido JSON node -e "console.log(JSON.parse(require('fs').readFileSync('/Users/jeff/Library/Application Support/Claude/claude_desktop_config.json', 'utf8')))"

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:

Verifique os logs do servidor:

# Com debug habilitado DEBUG=mcp-wppconnect:* npm start

Verifique os logs do Claude Desktop:

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

Teste manualmente:

# Execute o servidor diretamente node build/index.js # Deve mostrar "MCP WPPConnect Server connected and ready for requests"

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:

{ "mcpServers": { "mcp-wppconnect-server": { "command": "node", "args": ["/opt/mcp-wppconnect-server/build/index.js"], "env": { "NODE_ENV": "production", "MAX_SESSIONS": "20", "QR_EXPIRY_MINUTES": "10", "TOKEN_STORAGE_PATH": "/opt/mcp-wppconnect/tokens" } } } }

📚 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

{ "tool": "initialize_session", "arguments": { "sessionId": "minha-sessao-1" } }

Enviar uma mensagem

{ "tool": "send_text", "arguments": { "sessionId": "minha-sessao-1", "to": "5511999999999@c.us", "text": "Olá! Esta é uma mensagem do MCP WPPConnect Server." } }

Obter participantes de um grupo

{ "tool": "get_community_participants", "arguments": { "sessionId": "minha-sessao-1", "communityId": "551199999999-1234567890@g.us" } }

⚙️ Configuração

Variáveis de Ambiente

NODE_ENV=production # Ambiente (development/production) DEBUG=mcp-wppconnect:* # Habilitar logs detalhados MAX_SESSIONS=10 # Limite de sessões simultâneas QR_EXPIRY_MINUTES=5 # Tempo de expiração do QR code TOKEN_STORAGE_PATH=~/.mcp-wppconnect/tokens # Caminho dos tokens

🚨 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

Faça fork do projeto
Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
Commit suas mudanças (git commit -m 'Add some AmazingFeature')
Push para a branch (git push origin feature/AmazingFeature)
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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables WhatsApp automation through MCP protocol, allowing users to manage sessions, send messages, handle groups/communities, and access contacts through natural language interactions with AI agents.