mcp-whatsapp-cloud

@codespar/mcp-whatsapp-cloud

MCP server for the WhatsApp Cloud API — Meta's official WhatsApp Business API, self-hosted on Meta infrastructure.

Direct Meta integration. No middleman, no provider markup. For merchants with an approved WhatsApp Business Account (WABA) who want Meta-direct pricing and full control over conversation, pricing category, and template lifecycle.

WhatsApp servers in this catalog

Server	What it is	When to pick it
whatsapp-cloud (this)	Direct Meta Cloud API	Large merchants with approved WABA; lower cost at scale, no intermediary fees
z-api	Wrapper on top of Meta Cloud	Easy onboarding, instant QR-pair, extra helpers
evolution-api	Open-source wrapper	Self-hosted, community-driven
take-blip	Brazilian BSP wrapper	Enterprise Brazil, CCaaS features
zenvia	Brazilian BSP wrapper	Brazil omnichannel (SMS + WhatsApp)

Tools (22)

Tool	Purpose
send_text_message	Send a plain text message.
send_template_message	Send an approved message template.
send_media_message	Send an image, video, document, or audio.
send_interactive_message	Send an interactive message (reply buttons or list).
send_interactive_cta_url	Send an interactive message with a single CTA URL button.
send_interactive_flow	Send a WhatsApp Flow message.
send_location_message	Send a location pin with latitude/longitude and optional name/address.
send_contacts_message	Send one or more contact cards (vCard-like).
send_reaction_message	Send an emoji reaction on a previously received/sent message.
send_typing_indicator	Show a typing indicator on a received message.
mark_message_as_read	Mark an incoming message as read so the sender sees the blue double-check.
upload_media	Upload a media file and get back a media_id reusable in send_media_message.
retrieve_media_url	Resolve a media_id to a short-lived downloadable URL.
delete_media	Delete an uploaded media asset by id.
list_templates	List message templates on the WhatsApp Business Account.
create_template	Submit a new template for Meta review.
delete_template	Delete a message template from the WABA by name.
get_business_profile	Read the WhatsApp business profile (about, description, email, websites, vertical, address) for the configu...
update_business_profile	Update the business profile on the configured phone number.
list_phone_numbers	List all phone numbers registered under the WhatsApp Business Account, including display name, quality rati...
request_verification_code	Request Meta to send a verification code to the configured phone number via SMS or voice.
verify_code	Submit the verification code received via SMS/voice after request_verification_code.

Install

npm install @codespar/mcp-whatsapp-cloud

Environment

WHATSAPP_ACCESS_TOKEN="EAAG..."           # required (secret) — Meta system-user token
WHATSAPP_PHONE_NUMBER_ID="1234567890"     # required — WABA phone number id
WHATSAPP_BUSINESS_ACCOUNT_ID="9876543210" # required — WABA id (for templates)
WHATSAPP_GRAPH_VERSION="v21.0"            # optional — Meta bumps quarterly

Authentication

Bearer token against the Graph API. Use a permanent system-user token from Meta Business Manager — user access tokens expire and will break production.

Authorization: Bearer <WHATSAPP_ACCESS_TOKEN>

Messaging rules (important)

• Customer-service window — You can freely send any message type for 24h after the user last messaged you.
• Business-initiated — Outside that window you must send an approved template. Use send_template_message with a name + language + components.
• Templates — Create with create_template, wait for Meta approval (minutes to hours), then use.
• Phone numbers are E.164 without the leading + (e.g. 5511999999999).

Media

Two paths:

1. Public URL — pass link to send_media_message. Fastest, but Meta fetches on every send.
2. Uploaded media_id — call upload_media once, reuse id on subsequent sends. Recommended for catalog assets.

Uploaded media expires after ~30 days.

Interactive messages

send_interactive_message expects a fully-formed interactive object. Example button payload:

{
  "type": "button",
  "body": { "text": "Confirma seu pedido?" },
  "action": {
    "buttons": [
      { "type": "reply", "reply": { "id": "confirm", "title": "Confirmar" } },
      { "type": "reply", "reply": { "id": "cancel", "title": "Cancelar" } }
    ]
  }
}

See the Cloud API interactive reference for list payloads.

Run

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-whatsapp-cloud

# HTTP (for server-to-server)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-whatsapp-cloud

Enterprise

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT