uazapi-mcp
Provides speech-to-text transcription of WhatsApp audio messages and local audio files using ElevenLabs' Scribe v2 API.
Allows reading, searching, filtering, and downloading WhatsApp messages and media, with automatic transcription of audio messages and capabilities to send messages and reactions through the uazapi backend.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@uazapi-mcp what did the client say in the Support group today?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
uazapi-mcp
Seu WhatsApp dentro do Claude Code — com os áudios já transcritos.
Servidor MCP para ler, transcrever e enviar mensagens de WhatsApp pela uazapi.
O problema que isso resolve
Um cliente manda um áudio de dois minutos explicando um bug, mais três prints. Hoje o caminho é: abrir o WhatsApp, baixar o áudio, mover para uma pasta, rodar alguma ferramenta de transcrição, baixar cada imagem, copiar tudo para o agente — e só então começar a trabalhar.
Com este MCP, é uma pergunta:
> o que o cliente falou no grupo Suporte hoje?
[09:12] Marcos: [áudio] transcrição: "Bom dia, o sistema travou na hora de emitir a
nota, aparece um erro de conexão e não deixa salvar o pedido. Já tentei três vezes..."
[09:14] Marcos: [imagem] arquivo: ~/.uazapi-mcp/media/comercial/suporte/1757930040000-image.jpg
[09:15] NÓS: Já estamos olhando, Marcos.O áudio volta como texto. A imagem volta como arquivo local, pronto para o agente abrir.
Related MCP server: WAHA MCP Server
O que dá para fazer
Você pede | O que acontece |
"o que chegou do cliente X hoje" | Conversa do dia, áudios transcritos, prints baixados |
"as mensagens do grupo entre 10/09 e 12/09" | Janela fechada, agrupada por dia |
"só os áudios da última semana" | Filtra por tipo no servidor e transcreve cada um |
"procura onde falaram de reembolso" | Varredura nas conversas recentes |
"manda esse resumo pro cliente" | Prévia com destino resolvido → sua confirmação → envio |
"quais grupos eu tenho?" | Lista com identificadores |
Instalação
Precisa de uv, git e Python 3.11+. Não precisa clonar — o
uvx baixa e roda direto do repositório:
claude mcp add uazapi \
--env UAZAPI_SERVER=https://suaempresa.uazapi.com \
--env UAZAPI_ADMIN_TOKEN=seu_admin_token \
--env ELEVENLABS_API_KEY=sua_chave_elevenlabs \
-- uvx --from git+https://github.com/illumi-ai/uazapi-mcp uazapi-mcpPara fixar uma versão, troque a origem por git+https://github.com/illumi-ai/uazapi-mcp@v0.1.0.
As versões estão em Releases, cada uma com
wheel e sdist anexados.
Reinicie a sessão e peça ao agente para rodar check_config — ele confirma a conexão e
lista as instâncias conectadas, sem revelar segredos.
{
"mcpServers": {
"uazapi": {
"command": "uvx",
"args": ["--from", "git+https://github.com/illumi-ai/uazapi-mcp", "uazapi-mcp"],
"env": {
"UAZAPI_SERVER": "https://suaempresa.uazapi.com",
"UAZAPI_ADMIN_TOKEN": "seu_admin_token",
"ELEVENLABS_API_KEY": "sua_chave_elevenlabs"
}
}
}
}Skills (recomendado)
O repositório traz três skills que ensinam ao agente os fluxos completos:
Skill | Para que serve |
| Ler, buscar, baixar mídia e responder. A base |
| Relato espalhado do cliente vira documento estruturado, com timeline, evidências e severidade |
| Briefing: o que chegou, o que está sem resposta, o que precisa de decisão |
git clone https://github.com/illumi-ai/uazapi-mcp
cp -r uazapi-mcp/skills/whatsapp uazapi-mcp/skills/entender-problema uazapi-mcp/skills/resumo-do-dia ~/.claude/skills/Detalhes e como adaptar ao seu fluxo em skills/README.md.
Configuração
Variável | Obrigatória | Para que serve |
| sim | Servidor da sua conta, ex.: |
| sim¹ | Lista as instâncias e resolve o token de cada uma pelo nome |
| sim¹ | Alternativa: token de uma instância, se você só tem acesso a ela |
| não | Instância usada quando a chamada não informa |
| não | Transcrição (Scribe v2). Sem ela o áudio é baixado, não transcrito |
| não | Onde gravar as mídias (padrão |
| não | Tetos por chamada: |
¹ Um dos dois. Ambos os tokens saem do painel da uazapi.
As variáveis também podem ficar num .env em ~/.uazapi-mcp/.env ou em ~/.claude/.env,
nessa ordem e sempre atrás das variáveis já exportadas. Copie de
.env.example. O .env do diretório de trabalho não é lido: o cliente
MCP inicia o servidor dentro do projeto aberto, e um .env de terceiros não pode apontar
UAZAPI_SERVER — e o token junto — para outro lugar.
Tools
Parâmetros completos em docs/tools.md.
Datas em português
get_messages, get_media e search_messages entendem data como gente fala:
Expressão | Significado |
| O dia inteiro (repita em |
| A partir de agora |
| Desde o início da semana/mês corrente |
| Data brasileira, hora opcional |
| ISO |
| Intervalo, no campo |
Enviar exige duas etapas
send_text e send_media com confirmar=False (o padrão) não enviam nada: devolvem
uma prévia com a instância, o destino já resolvido, se é grupo, e o conteúdo. Só a
repetição com confirmar=True dispara.
O destino quase sempre vem de um nome parcial. A prévia é o que impede a mensagem de cair no grupo errado — e mensagem enviada em grupo de cliente não tem desfazer.
Limites da API (medidos, não supostos)
A documentação da uazapi promete algumas coisas que o servidor não entrega. Tudo abaixo foi verificado com chamadas reais e testes discriminantes — o raciocínio completo está em
docs/api-uazapi.md.
Não existe filtro de data no servidor.
/message/findignoramessageTimestamp,dateStart/dateEnde variações. O recorte por período é feito no cliente, paginando do mais recente para trás: barato para janelas recentes, caro para varrer meses.fromMeemessageTypefiltram server-side — conferido contra a contagem real do chat. Por isso pedir só os áudios é eficiente.transcribe: truedo/message/downloadpode não transcrever: depende de uma chave OpenAI configurada no servidor uazapi. Sem ela, devolve só o arquivo, sem erro. Daí a transcrição local via Scribe v2.O
fileURLda uazapi é público, sem autenticação — confirmado baixando o arquivo sem nenhum token. Este servidor grava a mídia em disco e devolve o caminho; o link nunca circula.A uazapi expurga o histórico antigo em poucos dias. Para períodos que o
get_messagesnão alcança, usesync_history(exige o celular do dono online).Mídia antiga expira no WhatsApp e não volta. O transcript registra o que era.
Privacidade
Conversa de WhatsApp é dado pessoal de terceiro. Este servidor grava mídias no disco local
e, quando você configura a chave, as transcrições passam pela API da ElevenLabs. Use com a
autorização de quem é dono do número, mantenha a pasta de mídias fora de qualquer
repositório (o .gitignore já cobre) e apague o que não precisa mais.
As tools de envio existem, mas este projeto não implementa disparo em massa — a API da
uazapi tem /sender/* para isso, e é justamente o tipo de ferramenta que não deve ficar a
uma chamada de distância de um agente autônomo.
Encontrou uma vulnerabilidade? Veja SECURITY.md — reporte em privado, não em issue pública.
Desenvolvimento
git clone https://github.com/illumi-ai/uazapi-mcp && cd uazapi-mcp
cp .env.example .env # preencha
uv sync
uv run --group dev pytest # testes, sem rede
uv run --group dev ruff check src tests
uv run --env-file .env uazapi-mcp # servidor em stdioApontar o Claude Code para o clone local:
claude mcp add uazapi -- uv run --env-file /caminho/para/uazapi-mcp/.env --directory /caminho/para/uazapi-mcp uazapi-mcpContribuições e processo de release: CONTRIBUTING.md · Histórico: CHANGELOG.md · Instruções para agentes: CLAUDE.md
Licença
MIT — veja LICENSE. Projeto independente, sem vínculo com a uazapi ou com o WhatsApp.
Available Tools
14 toolscheck_configA
Mostra o estado da configuração e testa a conexão com o servidor uazapi.
Use quando as outras tools falharem: diz o que falta configurar sem revelar segredos.
Inputs: no named parameters. Returns: result
get_chat_infoC
Detalhes de um contato ou grupo: identificador, nome, se é grupo, última mensagem.
Inputs: chat (required), instance. Returns: result
get_mediaA
Baixa as mídias de uma conversa para disco e devolve os caminhos locais.
tipos: 'all', 'audio', 'imagem', 'video' ou 'documento'. Áudios voltam também com a transcrição. Use quando precisar dos arquivos em si; para ler a conversa inteira prefira get_messages.
Inputs: chat (required), since, tipos, until, +3 more. Returns: result
get_messagesA
Lê as mensagens de uma conversa em uma janela de tempo, já com os áudios transcritos.
chat: nome do contato/grupo, número (5562...) ou identificador completo. since/until: 'hoje', 'ontem', '3d', '2h', '10/09', '10/09 14:30', '2026-09-10'. Tambem aceita intervalo em since: '10/09..12/09'. Vazio = mais recentes. transcrever_audios: áudios voltam como texto (ElevenLabs Scribe v2). baixar_midias: imagens/vídeos/documentos são gravados em disco e o caminho vem no transcript, pronto para o Read. tipo_mensagem: filtra por tipo, ex 'AudioMessage', 'ImageMessage', 'DocumentMessage'.
Inputs: chat (required), since, until, limite, +5 more. Returns: result
list_chatsA
Lista conversas ordenadas pela mais recente.
busca: parte do nome do contato/grupo (deixe vazio para as mais recentes). tipo: 'all', 'group' (só grupos) ou 'dm' (só individuais). instance: nome ou número da instância; vazio usa a padrão.
Inputs: tipo, busca, limite, instance. Returns: result
list_groupsC
Lista os grupos de que o número participa, com o identificador de cada um.
Inputs: busca, limite, instance. Returns: result
list_instancesA
Lista as instâncias (números de WhatsApp) disponiveis no servidor uazapi.
Use para descobrir qual valor passar em instance nas outras tools.
Inputs: apenas_conectadas. Returns: result
mark_readC
Marca como lidas as últimas mensagens recebidas de uma conversa.
Inputs: chat (required), instance, quantidade. Returns: result
reactA
Reage a uma mensagem. emoji vazio remove a reação.
Inputs: chat (required), message_id (required), emoji, instance. Returns: result
search_messagesB
Procura um termo nas mensagens recentes (a uazapi não busca texto no servidor).
chat vazio = varre os chats mais recentes; com chat, busca só nele.
Inputs: termo (required), chat, since, instance, +1 more. Returns: result
send_mediaB
Envia um arquivo local ou URL. Exige confirmação em duas etapas, como send_text.
tipo: image, video, document, audio, ptt (áudio de voz) ou sticker.
Inputs: chat (required), arquivo (required), tipo, legenda, +2 more. Returns: result
send_textA
Envia uma mensagem de texto. Exige confirmação em duas etapas.
Chame primeiro com confirmar=False: nada é enviado e volta um preview com o destinatario resolvido. MOSTRE esse preview ao usuário e só chame de novo com confirmar=True depois que ele aprovar.
Inputs: chat (required), texto (required), instance, confirmar, +1 more. Returns: result
sync_historyA
Pede ao celular o histórico antigo de uma conversa (assincrono).
Use só quando get_messages não alcança o período pedido: a uazapi guarda uma janela curta. Exige o celular online. As mensagens aparecem no get_messages depois de alguns segundos/minutos.
Inputs: chat (required), instance, quantidade. Returns: result
transcribe_fileA
Transcreve um arquivo de áudio local (ElevenLabs Scribe v2).
Útil para áudios já baixados por get_media ou vindos de outro lugar.
Inputs: caminho (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools have clearly distinct purposes, but there is some overlap between list_chats with tipo='group' and list_groups, and between get_messages (which can download/transcribe media) and get_media/transcribe_file. The descriptions help clarify the boundaries, so an agent can usually select the right tool.
Nearly every tool follows a clean snake_case verb_noun pattern like list_instances, send_text, and mark_read. The lone exception is 'react', which is a bare verb without an explicit object, making the naming slightly inconsistent.
With 14 tools, the set is well-scoped for a WhatsApp integration: it covers messaging, media, search, reactions, history sync, and configuration without feeling fragmented. Each tool has a functional role that earns its place.
The core WhatsApp workflow is well covered: listing instances/chats/groups, reading and searching messages, sending text/media, reacting, marking read, syncing history, and downloading/transcribing media. Missing group/contact management or message deletion are minor gaps for a chat-focused MCP server.
Maintenance
Related MCP Connectors
WhatsApp for Claude, ChatGPT or any AI agent: search, reply and send. Personal or Business API.
Read, summarize and send your own WhatsApp messages from AI assistants (OAuth 2.1).
WhatsApp CRM for AI agents: search contacts, read chats, manage the sales pipeline, send messages.
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with your personal WhatsApp account, allowing them to search messages and contacts, retrieve chat history, and send messages to individuals or groups. Uses WhatsApp Web API with local data storage for privacy and security.ISC
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with WhatsApp through the WAHA (WhatsApp HTTP API) platform. Supports chat management, message operations including sending/receiving messages, and marking chats as read.5211ISC
- FlicenseNot gradedqualityNot gradedmaintenanceEnables interaction with WhatsApp through the Uazapi API, allowing users to send text and media messages, manage contacts, and list conversations through natural language.-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to manage WhatsApp: list chats, send and receive messages, download media, and transcribe voice notes via the unofficial Baileys library.93 npmMIT