Skip to main content
Glama
Sign In
WhatsApp Business MCP Server

WhatsApp Business MCP Server

by EvandroSchechtel
OverviewSchemaSourceRelated ServersDiscussions(1)Admin
JavaScript
Remote

@bridgeapi/mcp-whatsapp

MCP Server para WhatsApp Business Cloud API — Conecte qualquer AI Agent ao WhatsApp via Model Context Protocol.

Parte do ecossistema BridgeAPI: conectores MCP para plataformas brasileiras.

O que faz

Este MCP server expõe a WhatsApp Business Cloud API como tools padronizados do Model Context Protocol. Isso permite que qualquer AI Agent (Claude, ChatGPT, LangChain, CrewAI, etc.) envie mensagens, gerencie templates, consulte analytics e muito mais — tudo via MCP.

Tools disponíveis

Tool

Descrição

send_text_message

Envia mensagem de texto (dentro da janela de 24h)

send_template_message

Envia template pré-aprovado (fora da janela de 24h)

send_media_message

Envia imagem, vídeo, áudio ou documento

send_interactive_message

Envia mensagem com botões ou lista

send_location_message

Envia localização

send_contact_message

Envia cartão de contato

mark_message_read

Marca mensagem como lida

list_templates

Lista templates com status de aprovação

create_template

Cria novo template para aprovação

delete_template

Deleta template

get_phone_numbers

Lista números com quality rating

get_business_profile

Retorna perfil do negócio

update_business_profile

Atualiza perfil

get_analytics

Métricas de mensagens por período

upload_media

Upload de mídia para envio

get_media_url

URL de download de mídia recebida

Resources (contexto read-only)

Resource

URI

Templates ativos

whatsapp://templates

Perfil do negócio

whatsapp://profile

Números registrados

whatsapp://phone-numbers

Prompts (guias reutilizáveis)

Prompt

Uso

campaign-sender

Guia para enviar campanha de marketing

support-responder

Guia para responder suporte

template-creator

Guia para criar templates seguindo regras da Meta

Instalação

npm install @bridgeapi/mcp-whatsapp

Configuração

Variáveis de ambiente obrigatórias

export WHATSAPP_ACCESS_TOKEN="your-system-user-token"
export WHATSAPP_PHONE_NUMBER_ID="your-phone-number-id"
export WHATSAPP_BUSINESS_ACCOUNT_ID="your-waba-id"
# Opcional:
export WHATSAPP_API_VERSION="v21.0"  # default

Como obter: Acesse Meta Business Manager → WhatsApp → Configuração da API.

Uso com Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["@bridgeapi/mcp-whatsapp"],
      "env": {
        "WHATSAPP_ACCESS_TOKEN": "your-token",
        "WHATSAPP_PHONE_NUMBER_ID": "your-phone-id",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "your-waba-id"
      }
    }
  }
}

Uso com Cursor

Adicione ao seu .cursor/mcp.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["@bridgeapi/mcp-whatsapp"],
      "env": {
        "WHATSAPP_ACCESS_TOKEN": "your-token",
        "WHATSAPP_PHONE_NUMBER_ID": "your-phone-id",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "your-waba-id"
      }
    }
  }
}

Exemplos de uso

Após configurar, você pode falar diretamente com o Claude:

Enviar mensagem

"Envie uma mensagem para +5541999999999 dizendo: Seu pedido #1234 foi enviado!"

Listar templates

"Quais templates de WhatsApp estão aprovados?"

Criar campanha

"Preciso criar uma campanha de marketing para o produto 'Curso de IA'. Me ajude a criar o template e enviar."

Ver analytics

"Mostre as métricas de mensagens dos últimos 7 dias."

Desenvolvimento

# Clone e instale
git clone https://github.com/bridgeapi-dev/mcp-whatsapp.git
cd mcp-whatsapp
npm install

# Build
npm run build

# Testar com MCP Inspector
npm run inspect

# Dev mode (watch)
npm run dev

Arquitetura

Agent (Claude/ChatGPT/LangChain)
    │
    ▼ (MCP Protocol - JSON-RPC 2.0)
┌──────────────────────────────┐
│  @bridgeapi/mcp-whatsapp     │
│  ┌────────────────────────┐  │
│  │ pre_execute hook  ◄────│──│── Phase 2: Execution Engine
│  │ (Phase 1: no-op + log) │  │
│  └────────┬───────────────┘  │
│           ▼                  │
│  ┌────────────────────────┐  │
│  │ WhatsApp Cloud API     │  │
│  │ (Meta Graph API v21.0) │  │
│  └────────┬───────────────┘  │
│           ▼                  │
│  ┌────────────────────────┐  │
│  │ post_execute hook ◄────│──│── Phase 2: Response validation
│  │ (Phase 1: no-op + log) │  │
│  └────────────────────────┘  │
└──────────────────────────────┘

Os hooks pre_execute e post_execute estão prontos para receber a Execution Engine na Fase 2 do BridgeAPI, mas na v0.1 são no-ops que apenas logam o contexto.

Roadmap

  • v0.1 — Tools core de messaging, templates, analytics, media

  • v0.2 — Webhook receiver para mensagens recebidas

  • v0.3 — Streamable HTTP transport (para uso remoto via Gateway)

  • v1.0 — Pronto para produção com rate limiting e error recovery

Ecossistema BridgeAPI

Conector

Status

WhatsApp Business API

✅ v0.1

Hotmart

🔜 Em desenvolvimento

Eduzz

🔜 Planejado

Pix / Pagamentos

🔜 Planejado

NFe / Notas Fiscais

🔜 Planejado

Guru

🔜 Planejado

Licença

MIT — use livremente.

Links

Available Tools

16 tools
create_templateA

Create a new message template for approval by Meta. Templates are required for outbound messages outside the 24-hour window.

Inputs: name (required), category (required), components (required), language.

delete_templateA

Delete a message template by name. This action is irreversible.

Inputs: template_name (required).

get_analyticsC

Get messaging analytics (sent, delivered, read counts) for a date range.

Inputs: start_date (required), end_date (required), granularity.

get_business_profileB

Get the WhatsApp Business profile (about, address, description, email, websites, profile picture).

Inputs: no named parameters.

get_media_urlA

Get the download URL for a received media file. URLs are valid for 5 minutes.

Inputs: media_id (required).

get_phone_numbersA

List all phone numbers registered on this WhatsApp Business Account, including quality rating and messaging limits.

Inputs: no named parameters.

list_templatesB

List all message templates in the WhatsApp Business Account, optionally filtered by status.

Inputs: status, limit.

mark_message_readB

Mark a received message as read (blue checkmarks). Use the message_id from a received webhook.

Inputs: message_id (required).

send_contact_messageC

Send a contact card to a WhatsApp number.

Inputs: to (required), contacts (required).

send_interactive_messageC

Send an interactive message with buttons or a selection list.

Inputs: to (required), interactive_type (required), body_text (required), buttons, +4 more.

send_location_messageC

Send a location pin to a WhatsApp number.

Inputs: to (required), latitude (required), longitude (required), name, +1 more.

send_media_messageC

Send an image, video, audio, or document to a WhatsApp number.

Inputs: to (required), media_type (required), media_url, media_id, +2 more.

send_template_messageA

Send a pre-approved template message. Required for initiating conversations outside the 24-hour window. Templates must be approved by Meta before use.

Inputs: to (required), template_name (required), language, components.

send_text_messageA

Send a text message to a WhatsApp number. Works within the 24-hour conversation window. For messages outside this window, use send_template_message instead.

Inputs: to (required), body (required), preview_url.

update_business_profileC

Update the WhatsApp Business profile information.

Inputs: about, description, address, email, +1 more.

upload_mediaB

Upload a media file for later sending. Returns a media_id that can be used with send_media_message.

Inputs: file_url (required), type (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 16 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose with no ambiguity. For example, send_text_message, send_media_message, and send_template_message each handle different message types, while get_business_profile and update_business_profile are clearly separate read and write operations. The descriptions reinforce these distinctions, making tool selection straightforward.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with clear, descriptive verbs like create, delete, get, list, mark, send, and update. There are no deviations in style (e.g., no camelCase or mixed conventions), making the naming highly predictable and readable throughout the set.

    Tool Count5/5

    With 16 tools, the server is well-scoped for managing a WhatsApp Business Account, covering key areas like messaging (text, media, templates, interactive), profile management, analytics, and media handling. Each tool earns its place without feeling excessive or thin, aligning well with the domain's complexity.

    Completeness5/5

    The tool set provides complete CRUD/lifecycle coverage for the WhatsApp Business domain. It includes creation (e.g., create_template, upload_media), retrieval (e.g., get_business_profile, list_templates), updates (e.g., update_business_profile, mark_message_read), and deletion (delete_template), with no obvious gaps that would hinder agent workflows.

    Resources

    Related MCP Connectors