README.md•10.7 kB
# 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
```bash
# 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
```bash
npm run dev
```
### Produção
```bash
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/`:
```bash
# 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**:
```json
{
"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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
# 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:
```bash
# 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](mcp-configs/README.md)
- [Guia de Deploy](DEPLOYMENT.md)
- [Solução de Problemas](TROUBLESHOOTING.md)
- [Exemplos de Uso](src/tools/README.md)
Configure o Claude Desktop para usar o servidor MCP:
### 1. Preparação
```bash
# 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):
```json
{
"mcpServers": {
"mcp-wppconnect-server": {
"command": "npm",
"args": ["run", "dev"],
"cwd": "/Users/jeff/Desktop/MCP CONNECT"
}
}
}
```
#### Para Produção (usando build):
```json
{
"mcpServers": {
"mcp-wppconnect-server": {
"command": "node",
"args": ["/Users/jeff/Desktop/MCP CONNECT/build/index.js"]
}
}
}
```
### 4. Validação da Configuração
```bash
# 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**:
```bash
# 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**:
```bash
# 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:
```json
{
"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
```json
{
"tool": "initialize_session",
"arguments": {
"sessionId": "minha-sessao-1"
}
}
```
### Enviar uma mensagem
```json
{
"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
```json
{
"tool": "get_community_participants",
"arguments": {
"sessionId": "minha-sessao-1",
"communityId": "551199999999-1234567890@g.us"
}
}
```
## ⚙️ Configuração
### Variáveis de Ambiente
```bash
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](https://github.com/wppconnect-team) pelo excelente trabalho com a biblioteca WPPConnect
- [Model Context Protocol](https://modelcontextprotocol.io) pela especificação MCP
## 📞 Suporte
Para problemas e dúvidas:
- Abra uma issue no GitHub
- Consulte o guia [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
- Verifique a documentação em [src/tools/README.md](./src/tools/README.md)