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

📁 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

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

# 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

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

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

1. Verifique os logs do servidor:

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

2. Verifique os logs do Claude Desktop:

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

3. Teste manualmente:

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

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:

{
  "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

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