# Uazapi MCP Server
MCP Server para integração com a API Uazapi WhatsApp v2.0
## Visão Geral
Este servidor MCP (Model Context Protocol) permite que LLMs interajam com a API do Uazapi para enviar e gerenciar mensagens no WhatsApp. Ele fornece ferramentas para:
- ✉️ Enviar mensagens de texto
- 📎 Enviar mídia (imagens, vídeos, áudios, documentos)
- 👥 Gerenciar contatos
- 💬 Listar conversas
- 🔄 E mais funcionalidades conforme documentação da API
## Instalação
### 1. Instalar Dependências
```bash
# Usando uv (recomendado)
uv pip install -r requirements.txt
# Ou usando pip
pip install -r requirements.txt
```
### 2. Configurar Variáveis de Ambiente
Você precisa configurar suas credenciais da Uazapi:
```bash
export UAZAPI_API_KEY="sua_chave_api_aqui"
export UAZAPI_INSTANCE_ID="seu_instance_id_aqui"
```
**Como obter suas credenciais:**
1. Acesse https://uazapi.com/
2. Faça login na sua conta
3. Vá para a seção de API
4. Copie seu API Key e Instance ID
### 3. Testar o Servidor
```bash
# Verificar sintaxe
python -m py_compile uazapi_mcp.py
# Testar execução com timeout
timeout 5s python uazapi_mcp.py || echo "Server started successfully"
```
### 4. Instalar no Claude Desktop
```bash
# Usando uv
uv run mcp install uazapi_mcp.py --name "Uazapi WhatsApp"
# Ou adicionar manualmente ao claude_desktop_config.json
```
**Configuração manual no `claude_desktop_config.json`:**
```json
{
"mcpServers": {
"uazapi": {
"command": "python",
"args": ["/caminho/completo/para/uazapi_mcp.py"],
"env": {
"UAZAPI_API_KEY": "sua_chave_aqui",
"UAZAPI_INSTANCE_ID": "seu_instance_id_aqui"
}
}
}
}
```
## Ferramentas Disponíveis
### 1. `uazapi_send_text_message`
Envia mensagem de texto para um contato do WhatsApp.
**Parâmetros:**
- `phone` (string): Número do destinatário com código do país (ex: "5511999999999")
- `message` (string): Conteúdo da mensagem (1-4096 caracteres)
**Exemplo de uso:**
```
Envie "Olá, tudo bem?" para +55 11 99999-9999
```
### 2. `uazapi_send_media_message`
Envia mídia (imagem, vídeo, áudio ou documento) para um contato.
**Parâmetros:**
- `phone` (string): Número do destinatário
- `media_url` (string): URL pública do arquivo (HTTPS)
- `media_type` (enum): Tipo da mídia (image/video/audio/document)
- `caption` (string, opcional): Legenda para a mídia
- `filename` (string, opcional): Nome do arquivo para documentos
**Exemplo de uso:**
```
Envie a imagem https://example.com/foto.jpg com legenda "Confira!" para 5511999999999
```
### 3. `uazapi_get_contacts`
Recupera lista de contatos do WhatsApp.
**Parâmetros:**
- `limit` (int, opcional): Máximo de contatos (1-100, padrão: 20)
- `offset` (int, opcional): Número de contatos para pular (padrão: 0)
- `response_format` (enum, opcional): Formato da resposta (markdown/json, padrão: markdown)
**Exemplo de uso:**
```
Liste meus contatos do WhatsApp
Mostre os primeiros 50 contatos em formato JSON
```
### 4. `uazapi_get_chats`
Recupera lista de conversas recentes.
**Parâmetros:**
- `limit` (int, opcional): Máximo de conversas (1-100, padrão: 20)
- `offset` (int, opcional): Número de conversas para pular (padrão: 0)
- `response_format` (enum, opcional): Formato da resposta (markdown/json)
**Exemplo de uso:**
```
Mostre minhas conversas recentes no WhatsApp
Liste os últimos 30 chats
```
## Características e Boas Práticas
### Validação de Entrada
- ✅ Todos os parâmetros são validados usando Pydantic v2
- ✅ Números de telefone são formatados automaticamente
- ✅ URLs são validadas antes do envio
- ✅ Limites de caracteres são aplicados
### Tratamento de Erros
- ✅ Mensagens de erro claras e acionáveis
- ✅ Orientação sobre como resolver problemas
- ✅ Tratamento específico para cada código de status HTTP
### Paginação
- ✅ Suporte para grandes conjuntos de dados
- ✅ Metadados de paginação (`has_more`, `next_offset`, `total_count`)
- ✅ Limites padrão razoáveis (20 itens)
### Truncamento
- ✅ Limite de 25.000 caracteres por resposta
- ✅ Truncamento gracioso com mensagens claras
- ✅ Orientação sobre como obter mais dados
### Formatos de Resposta
- ✅ **Markdown**: Para leitura humana, formatado e organizado
- ✅ **JSON**: Para processamento programático, dados completos
## Segurança
- 🔒 API Keys armazenadas em variáveis de ambiente (nunca no código)
- 🔒 Validação de entrada para prevenir injeção
- 🔒 URLs validadas (apenas HTTPS para mídia)
- 🔒 Rate limiting tratado adequadamente
- 🔒 Mensagens de erro não expõem detalhes internos
## Desenvolvimento
### Estrutura do Código
```
uazapi_mcp.py
├── Imports e Configuração
├── Constantes (API_BASE_URL, CHARACTER_LIMIT)
├── Enums (ResponseFormat, MessageType)
├── Funções Utilitárias Compartilhadas
│ ├── _validate_auth()
│ ├── _get_auth_headers()
│ ├── _make_api_request()
│ ├── _handle_api_error()
│ ├── _format_phone_number()
│ └── _truncate_response()
├── Modelos Pydantic para Validação
│ ├── SendTextMessageInput
│ ├── SendMediaMessageInput
│ ├── GetContactsInput
│ └── GetChatsInput
├── Implementações de Ferramentas
│ ├── uazapi_send_text_message
│ ├── uazapi_send_media_message
│ ├── uazapi_get_contacts
│ └── uazapi_get_chats
└── Entry Point (if __name__ == "__main__")
```
### Adicionar Novos Endpoints
Para adicionar novos endpoints da API Uazapi:
1. **Criar Modelo Pydantic** para validação de entrada
2. **Implementar função de ferramenta** com decorador `@mcp.tool()`
3. **Usar funções utilitárias** compartilhadas (`_make_api_request`, `_handle_api_error`)
4. **Adicionar anotações** apropriadas (readOnlyHint, destructiveHint, etc.)
5. **Documentar** com docstring completa e exemplos
**Exemplo de template:**
```python
class NovoEndpointInput(BaseModel):
"""Descrição do modelo."""
model_config = ConfigDict(
str_strip_whitespace=True,
validate_assignment=True,
extra='forbid'
)
param1: str = Field(..., description="Descrição")
@mcp.tool(
name="uazapi_novo_endpoint",
annotations={
"title": "Título Legível",
"readOnlyHint": True, # Ajustar conforme necessário
"destructiveHint": False,
"idempotentHint": True,
"openWorldHint": True
}
)
async def uazapi_novo_endpoint(params: NovoEndpointInput) -> str:
"""
Descrição completa da ferramenta.
Args:
params: Documentação dos parâmetros
Returns:
Descrição do retorno com exemplos
"""
try:
response = await _make_api_request(
endpoint="caminho/do/endpoint",
method="GET",
params={"key": params.param1}
)
return format_response(response)
except Exception as e:
return _handle_api_error(e)
```
## Próximos Passos
Para expandir este servidor, você pode adicionar:
- [ ] Grupos e Comunidades
- Criar grupos
- Adicionar/remover participantes
- Enviar mensagens para grupos
- Gerenciar admins
- [ ] Mensagens Avançadas
- Enviar localização
- Enviar contatos
- Enviar stickers
- Mensagens agendadas
- Respostas rápidas
- [ ] Status e Presença
- Atualizar status
- Ver status de contatos
- Gerenciar presença (online/offline)
- [ ] Webhooks e Eventos
- Configurar webhooks
- Receber mensagens
- Notificações de status
- [ ] Mensagens e Histórico
- Buscar mensagens
- Recuperar histórico de conversas
- Marcar como lido/não lido
## Documentação da API
Para mais detalhes sobre os endpoints disponíveis, consulte:
- **Documentação oficial**: https://docs.uazapi.com/
- **Enviar Mensagem**: https://docs.uazapi.com/tag/Enviar%20Mensagem
- **Contatos**: https://docs.uazapi.com/tag/Contatos
- **Grupos**: https://docs.uazapi.com/tag/Grupos%20e%20Comunidades
## Suporte e Contribuições
Este é um servidor MCP base com as funcionalidades essenciais. Você pode:
1. **Estender** adicionando novos endpoints
2. **Customizar** ajustando limites e formatos
3. **Integrar** com outros MCP servers
4. **Compartilhar** suas melhorias
## Licença
Este projeto é fornecido como exemplo de implementação de MCP server.
---
**Desenvolvido com ❤️ usando [MCP (Model Context Protocol)](https://modelcontextprotocol.io/)**