Which integrations are available for this server?

Enables management of WhatsApp sessions, sending text messages, managing group and community participants, and retrieving contacts and chats through the WPPConnect library.

How do I use MCP WPPConnect Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP WPPConnect Server send a message to Maria saying I'll be 10 minutes late" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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