mcp-uazapi by Tiag8 - MCP Server

MCP UAZAPI

MCP Server para integração WhatsApp via UAZAPI

Um servidor Model Context Protocol (MCP) que encapsula os 17 patterns validados em produção para integração WhatsApp via UAZAPI, permitindo que agentes de IA enviem mensagens, stickers, mídia e áudios de forma robusta.

📚 Índice

Visão Geral
Features
Instalação
Configuração
Uso
- Claude Desktop
- Outros MCP Clients
Tools Disponíveis
Desenvolvimento
Patterns Implementados
Troubleshooting
Referências

Visão Geral

O MCP UAZAPI é um servidor MCP que fornece uma camada de abstração robusta para integração com a API do UAZAPI WhatsApp. Ele encapsula 17 patterns validados em produção, incluindo:

Autenticação correta (token header, não Bearer)
Normalização de telefone brasileiro (13 dígitos com 9º dígito)
Envio de mensagens texto, stickers WEBP animados, mídia (imagem/vídeo/documento)
Envio de áudios PTT (voice notes)
Validação e normalização de números brasileiros

Este servidor foi desenvolvido para ser usado por outros projetos que precisam de capacidades de mensageria WhatsApp, eliminando a necessidade de reimplementar os patterns complexos do UAZAPI.

Stack:

Runtime: Node.js 20+
Linguagem: TypeScript 5.3+
Protocolo: MCP via stdio
API: UAZAPI WhatsApp

Features

✅ 5 Tools Prontas para Uso:

Tool	Descrição
`send_message`	Envia mensagem texto WhatsApp
`send_sticker`	Envia sticker WEBP animado
`send_media`	Envia imagem/vídeo/documento
`send_audio`	Envia áudio PTT (voice note)
`validate_phone`	Valida e normaliza telefone brasileiro

✅ 17 Patterns Validados em Produção:

Token authentication (header token, não Authorization Bearer)
Phone normalization (auto-adiciona 9º dígito celular)
Media como base64 (não URL direta)
Sticker WEBP (único formato animado suportado)
Audio PTT via /send/media
Retry logic com exponential backoff
Error handling robusto (401, 400, 500)
LGPD compliance patterns
Button extraction (UAZAPI format changes)
E muito mais (ver Patterns Implementados)

✅ Type-Safe e Documentado:

TypeScript com tipos completos
Validação de schemas
Error messages descritivos
Logs estruturados

Instalação

# Clone o repositório
git clone https://github.com/seu-usuario/mcp-uazapi.git
cd mcp-uazapi

# Instale as dependências
npm install

# Build o projeto
npm run build

Requisitos:

Node.js 20 ou superior
npm 9 ou superior
Conta UAZAPI ativa com token válido

Configuração

1. Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

# URL do servidor UAZAPI
UAZAPI_SERVER_URL=https://stackia.uazapi.com

# Token da sua instância UAZAPI
UAZAPI_INSTANCE_TOKEN=seu-token-aqui

Como obter o token:

Acesse UAZAPI Console
Crie uma instância WhatsApp
Copie o token da instância
Cole no .env

2. Validar Token (cURL)

# Teste se o token está funcionando
curl --request POST \
  --url https://stackia.uazapi.com/send/text \
  --header 'token: SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "number": "5562992451477",
    "text": "Test message"
  }'

# Esperado: 200 OK
# Se 401: Token inválido ou expirado

Uso

Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "uazapi": {
      "command": "node",
      "args": ["/caminho/absoluto/para/mcp-uazapi/dist/index.js"],
      "env": {
        "UAZAPI_SERVER_URL": "https://stackia.uazapi.com",
        "UAZAPI_INSTANCE_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Reinicie o Claude Desktop após salvar o arquivo.

Outros MCP Clients

Qualquer cliente MCP pode usar este servidor via stdio:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["/caminho/para/mcp-uazapi/dist/index.js"],
  env: {
    UAZAPI_SERVER_URL: "https://stackia.uazapi.com",
    UAZAPI_INSTANCE_TOKEN: "seu-token-aqui"
  }
});

const client = new Client(
  { name: "meu-cliente", version: "1.0.0" },
  { capabilities: {} }
);

await client.connect(transport);

Tools Disponíveis

1. `send_message`

Envia mensagem texto para WhatsApp.

Parâmetros:

{
  phone: string;    // "5562992451477" (13 dígitos)
  message: string;  // Mensagem texto (max 4096 chars)
}

Exemplo:

{
  "name": "send_message",
  "arguments": {
    "phone": "5562992451477",
    "message": "Olá! Esta é uma mensagem de teste."
  }
}

Retorno:

{
  "success": true,
  "messageId": "3EB0E5AB6F456C0F3C3B6BC0E5AB6F45"
}

2. `send_sticker`

Envia sticker WEBP animado para WhatsApp.

IMPORTANTE: WhatsApp só aceita stickers em formato WEBP animado. GIFs viram imagem estática.

Parâmetros:

{
  phone: string;       // "5562992451477" (13 dígitos)
  stickerUrl: string;  // URL pública do sticker WEBP
}

Exemplo:

{
  "name": "send_sticker",
  "arguments": {
    "phone": "5562992451477",
    "stickerUrl": "https://example.com/sticker-animated.webp"
  }
}

Como converter GIF para WEBP:

Acesse ezgif.com/gif-to-webp
Upload o GIF
Converta para WEBP
Download e hospede (Supabase Storage, S3, etc)

Retorno:

{
  "success": true,
  "messageId": "3EB0E5AB6F456C0F3C3B6BC0E5AB6F45"
}

3. `send_media`

Envia imagem, vídeo ou documento para WhatsApp.

Parâmetros:

{
  phone: string;      // "5562992451477" (13 dígitos)
  mediaUrl: string;   // URL pública da mídia
  mediaType: "image" | "video" | "document";
  caption?: string;   // Legenda opcional
}

Exemplo:

{
  "name": "send_media",
  "arguments": {
    "phone": "5562992451477",
    "mediaUrl": "https://example.com/foto.jpg",
    "mediaType": "image",
    "caption": "Confira esta imagem!"
  }
}

Formatos suportados:

Image: JPG, PNG, WEBP (max 16MB)
Video: MP4, AVI, MOV (max 16MB)
Document: PDF, DOC, DOCX, XLS, XLSX (max 100MB)

Retorno:

{
  "success": true,
  "messageId": "3EB0E5AB6F456C0F3C3B6BC0E5AB6F45"
}

4. `send_audio`

Envia áudio PTT (voice note) para WhatsApp.

Parâmetros:

{
  phone: string;      // "5562992451477" (13 dígitos)
  audioUrl: string;   // URL pública do áudio WAV/OGG/MP3
  ptt?: boolean;      // true = voice note (padrão), false = arquivo áudio
}

Exemplo:

{
  "name": "send_audio",
  "arguments": {
    "phone": "5562992451477",
    "audioUrl": "https://example.com/audio.wav",
    "ptt": true
  }
}

Diferença PTT vs Audio:

PTT (Push-to-Talk): Aparece como bolinha verde (voice note)
Audio: Aparece como arquivo de áudio (pode baixar)

Formatos suportados: WAV, OGG, MP3, AAC

Retorno:

{
  "success": true,
  "messageId": "3EB0E5AB6F456C0F3C3B6BC0E5AB6F45"
}

5. `validate_phone`

Valida e normaliza número de telefone brasileiro para formato WhatsApp.

Parâmetros:

{
  phone: string;  // Qualquer formato: "+55 62 9245-1477", "62992451477", etc
}

Exemplo:

{
  "name": "validate_phone",
  "arguments": {
    "phone": "+55 (62) 9 9245-1477"
  }
}

Retorno:

{
  "isValid": true,
  "normalized": "5562992451477",
  "format": {
    "countryCode": "55",
    "areaCode": "62",
    "number": "992451477"
  }
}

Validações automáticas:

Remove espaços, hífens, parênteses, +
Adiciona 9º dígito se celular com 12 dígitos
Valida formato E.164 (13 dígitos)
Valida código de país (55 = Brasil)
Valida DDD brasileiro

Desenvolvimento

Scripts Disponíveis

# Desenvolvimento com watch mode
npm run dev

# Build para produção
npm run build

# Lint (ESLint)
npm run lint

# Formatar código (Prettier)
npm run format

# Testes (se configurados)
npm test

Estrutura do Projeto

mcp-uazapi/
├── src/
│   ├── index.ts              # Entry point MCP server
│   ├── tools/                # Tool implementations
│   │   ├── send-message.ts   # Envio de mensagens texto
│   │   ├── send-sticker.ts   # Envio de stickers WEBP
│   │   ├── send-media.ts     # Envio de mídia
│   │   ├── send-audio.ts     # Envio de áudios PTT
│   │   └── validate-phone.ts # Validação telefone
│   └── utils/
│       ├── phone.ts          # Phone normalization
│       └── base64.ts         # URL to base64 converter
├── dist/                     # Build output (gerado)
├── .claude/
│   └── CLAUDE.md            # Regras específicas do projeto
├── package.json
├── tsconfig.json
└── README.md                # Este arquivo

Adicionando Novas Tools

Crie arquivo em src/tools/nova-tool.ts
Implemente a tool seguindo o pattern MCP
Registre no src/index.ts
Atualize este README

Template tool:

import { z } from "zod";

export const novaToolSchema = z.object({
  parametro: z.string().describe("Descrição do parâmetro"),
});

export async function novaTool(args: z.infer<typeof novaToolSchema>) {
  // Implementação
  return { success: true };
}

Patterns Implementados

Este servidor implementa 17 patterns validados em produção documentados em ~/.claude/memory/uazapi.md:

1. Critical Authentication Patterns

✅ Token em header token (não Authorization Bearer)
✅ Validação de token com cURL

2. Phone Number Normalization (Brazil)

✅ Formato E.164: 55 + DDD + 9 + 8 dígitos = 13 dígitos
✅ Auto-adição de 9º dígito para celulares com 12 dígitos
✅ Remoção de @s.whatsapp.net, +, -, espaços

3. Sending Messages (Correct API)

✅ Endpoint /send/text (não /send)
✅ Fields corretos: number + text
✅ Retry logic com exponential backoff

4. Sending Stickers (WEBP Animated)

✅ Endpoint /send/media com type: "sticker"
✅ Formato WEBP animado (único suportado)
✅ Conversão de URL para base64

5. Sending Audio Messages (PTT/Voice Notes)

✅ Endpoint /send/media com type: "ptt"
✅ Field file (não audio)
✅ Base64 puro (sem data URI prefix)

6. Media as Base64

✅ UAZAPI exige file: base64 para mídia
✅ Helper urlToBase64() para converter URLs

7. Message Formatting Best Practices

✅ Suporte a WhatsApp Markdown (*bold*, _italic_, etc)
✅ Limite de 4096 caracteres
✅ Rate limiting (30 msgs/hora recomendado)

8. Common Errors & Solutions

✅ Error 401: Token authentication correto
✅ Error 400: Phone validation
✅ Error 500: Retry logic

9-17. Patterns Avançados

Button parsing evolution
Webhook payload parsing
Message filtering rules
LGPD compliance patterns
Docker VPS deploy patterns
WhatsApp media decryption
Conversation pause/resume
Button detection by response text

Referência completa: ~/.claude/memory/uazapi.md (v1.7)

Troubleshooting

Erro 401 Unauthorized

Sintomas:

UAZAPI send failed: 401 - {"code":401,"message":"Missing token."}

Soluções:

✅ Verificar se token está em header token (não Authorization: Bearer)
✅ Verificar se token está correto (copiar do console UAZAPI)
✅ Verificar se token não expirou
✅ Verificar endpoint /send/text (não /send)

Erro 400 Invalid Number

Sintomas:

UAZAPI send failed: 400 - {"message":"Invalid number format"}

Soluções:

✅ Usar tool validate_phone para normalizar
✅ Garantir 13 dígitos (5562992451477)
✅ Remover +, espaços, hífens
✅ Verificar se 5º dígito é 9 (celular)

Sticker aparece como imagem estática

Causa: GIF não é suportado. WhatsApp só aceita WEBP animado.

Solução:

Converter GIF para WEBP: ezgif.com/gif-to-webp
Hospedar WEBP em URL pública
Usar tool send_sticker com URL do WEBP

Erro "text?.substring is not a function"

Causa: Payload UAZAPI é polimórfico (campo pode ser string OU objeto).

Solução: Já tratado automaticamente no MCP server. Se encontrar este erro, reporte no GitHub Issues.

Referências

Documentação Oficial

Patterns Validados

~/.claude/memory/uazapi.md - 17 patterns em produção (v1.7)
Life Tracker Project - Validação em produção desde 2025-11-23

Ferramentas Úteis

ezgif.com/gif-to-webp - Converter GIF para WEBP
UAZAPI Console - Gerenciar instâncias
Claude Desktop - Cliente MCP oficial

Licença

MIT License - Veja arquivo LICENSE para detalhes.

Contribuindo

Contribuições são bem-vindas! Por favor:

Fork o projeto
Crie uma branch (git checkout -b feature/nova-feature)
Commit suas mudanças (git commit -m 'feat: adiciona nova feature')
Push para a branch (git push origin feature/nova-feature)
Abra um Pull Request

Padrões de commit: Conventional Commits

Changelog

v1.0.0 (2025-12-04)

✅ Primeira versão estável
✅ 5 tools implementadas
✅ 17 patterns validados em produção
✅ Documentação completa em português

Desenvolvido com ❤️ por Tiago

Validado em produção: Life Tracker Project (2025-11-23 - presente)

Tiag8/mcp-uazapi

MCP UAZAPI

📚 Índice

Visão Geral

Features

Instalação

Configuração

1. Variáveis de Ambiente

2. Validar Token (cURL)

Uso

Claude Desktop

Outros MCP Clients

Tools Disponíveis

1. send_message

2. send_sticker

3. send_media

4. send_audio

5. validate_phone

Desenvolvimento

Scripts Disponíveis

Estrutura do Projeto

Adicionando Novas Tools

Patterns Implementados

1. Critical Authentication Patterns

2. Phone Number Normalization (Brazil)

3. Sending Messages (Correct API)

4. Sending Stickers (WEBP Animated)

5. Sending Audio Messages (PTT/Voice Notes)

6. Media as Base64

7. Message Formatting Best Practices

8. Common Errors & Solutions

9-17. Patterns Avançados

Troubleshooting

Erro 401 Unauthorized

Erro 400 Invalid Number

Sticker aparece como imagem estática

Erro "text?.substring is not a function"

Referências

Documentação Oficial

Patterns Validados

Ferramentas Úteis

Licença

Contribuindo

Changelog

v1.0.0 (2025-12-04)

1. `send_message`

2. `send_sticker`

3. `send_media`

4. `send_audio`

5. `validate_phone`