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

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

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

# 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

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

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

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)