Uazapi MCP Server

MCP Server para integrao com a API Uazapi WhatsApp v2.0

Viso 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 mdia (imagens, vdeos, udios, documentos)
• Gerenciar contatos
• Listar conversas
• E mais funcionalidades conforme documentao da API

Instalao

1. Instalar Dependncias

# Usando uv (recomendado)
uv pip install -r requirements.txt

# Ou usando pip
pip install -r requirements.txt

2. Configurar Variveis 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. Faa login na sua conta
3. V para a seo de API
4. Copie seu API Key e Instance ID

3. Testar o Servidor

# Verificar sintaxe
python -m py_compile uazapi_mcp.py

# Testar execuo 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

Configurao 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 Disponveis

1. uazapi_send_text_message

Envia mensagem de texto para um contato do WhatsApp.

Parmetros:

• phone (string): Nmero do destinatrio com cdigo do pas (ex: "5511999999999")
• message (string): Contedo da mensagem (1-4096 caracteres)

Exemplo de uso:

Envie "Ol, tudo bem?" para +55 11 99999-9999

2. uazapi_send_media_message

Envia mdia (imagem, vdeo, udio ou documento) para um contato.

Parmetros:

• phone (string): Nmero do destinatrio
• media_url (string): URL pblica do arquivo (HTTPS)
• media_type (enum): Tipo da mdia (image/video/audio/document)
• caption (string, opcional): Legenda para a mdia
• 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.

Parmetros:

• limit (int, opcional): Mximo de contatos (1-100, padro: 20)
• offset (int, opcional): Nmero de contatos para pular (padro: 0)
• response_format (enum, opcional): Formato da resposta (markdown/json, padro: 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.

Parmetros:

• limit (int, opcional): Mximo de conversas (1-100, padro: 20)
• offset (int, opcional): Nmero de conversas para pular (padro: 0)
• response_format (enum, opcional): Formato da resposta (markdown/json)

Exemplo de uso:

Mostre minhas conversas recentes no WhatsApp
Liste os ltimos 30 chats

Caractersticas e Boas Prticas

Validao de Entrada

• Todos os parmetros so validados usando Pydantic v2
• Nmeros de telefone so formatados automaticamente
• URLs so validadas antes do envio
• Limites de caracteres so aplicados

Tratamento de Erros

• Mensagens de erro claras e acionveis
• Orientao sobre como resolver problemas
• Tratamento especfico para cada cdigo de status HTTP

Paginao

• Suporte para grandes conjuntos de dados
• Metadados de paginao (has_more, next_offset, total_count)
• Limites padro razoveis (20 itens)

Truncamento

• Limite de 25.000 caracteres por resposta
• Truncamento gracioso com mensagens claras
• Orientao sobre como obter mais dados

Formatos de Resposta

• Markdown: Para leitura humana, formatado e organizado
• JSON: Para processamento programtico, dados completos

Segurana

• API Keys armazenadas em variveis de ambiente (nunca no cdigo)
• Validao de entrada para prevenir injeo
• URLs validadas (apenas HTTPS para mdia)
• Rate limiting tratado adequadamente
• Mensagens de erro no expem detalhes internos

Desenvolvimento

Estrutura do Cdigo

uazapi_mcp.py
 Imports e Configurao
 Constantes (API_BASE_URL, CHARACTER_LIMIT)
 Enums (ResponseFormat, MessageType)
 Funes Utilitrias Compartilhadas
    _validate_auth()
    _get_auth_headers()
    _make_api_request()
    _handle_api_error()
    _format_phone_number()
    _truncate_response()
 Modelos Pydantic para Validao
    SendTextMessageInput
    SendMediaMessageInput
    GetContactsInput
    GetChatsInput
 Implementaes 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 validao de entrada
2. Implementar funo de ferramenta com decorador @mcp.tool()
3. Usar funes utilitrias compartilhadas (_make_api_request, _handle_api_error)
4. Adicionar anotaes apropriadas (readOnlyHint, destructiveHint, etc.)
5. Documentar com docstring completa e exemplos

Exemplo de template:

class NovoEndpointInput(BaseModel):
    """Descrio do modelo."""
    model_config = ConfigDict(
        str_strip_whitespace=True,
        validate_assignment=True,
        extra='forbid'
    )

    param1: str = Field(..., description="Descrio")

@mcp.tool(
    name="uazapi_novo_endpoint",
    annotations={
        "title": "Ttulo Legvel",
        "readOnlyHint": True,  # Ajustar conforme necessrio
        "destructiveHint": False,
        "idempotentHint": True,
        "openWorldHint": True
    }
)
async def uazapi_novo_endpoint(params: NovoEndpointInput) -> str:
    """
    Descrio completa da ferramenta.

    Args:
        params: Documentao dos parmetros

    Returns:
        Descrio 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)

Prximos Passos

Para expandir este servidor, voc pode adicionar:

• Grupos e Comunidades

  • Criar grupos
  • Adicionar/remover participantes
  • Enviar mensagens para grupos
  • Gerenciar admins

• Mensagens Avanadas

  • Enviar localizao
  • Enviar contatos
  • Enviar stickers
  • Mensagens agendadas
  • Respostas rpidas

• Status e Presena

  • Atualizar status
  • Ver status de contatos
  • Gerenciar presena (online/offline)

• Webhooks e Eventos

  • Configurar webhooks
  • Receber mensagens
  • Notificaes de status

• Mensagens e Histrico

  • Buscar mensagens
  • Recuperar histrico de conversas
  • Marcar como lido/no lido

Documentao da API

Para mais detalhes sobre os endpoints disponveis, consulte:

• Documentao 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 Contribuies

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

Licena

Este projeto fornecido como exemplo de implementao de MCP server.

Desenvolvido com usando MCP (Model Context Protocol)