mcp-whatsapp-cloud — Claude Code MCP server: WhatsApp Cloud API
An MCP server for the WhatsApp Cloud API. Your agent sends messages, media and templates through Meta's Graph API directly.
claude mcp add --env WHATSAPP_ACCESS_TOKEN=<WHATSAPP_ACCESS_TOKEN> --env WHATSAPP_PHONE_NUMBER_ID=<WHATSAPP_PHONE_NUMBER_ID> --env WHATSAPP_BUSINESS_ACCOUNT_ID=<WHATSAPP_BUSINESS_ACCOUNT_ID> --env WHATSAPP_GRAPH_VERSION=<WHATSAPP_GRAPH_VERSION> --transport stdio whatsapp-cloud -- npx -y @codespar/mcp-whatsapp-cloudWhat mcp-whatsapp-cloud does
The server exposes 22 tools to an agent. Plain text, approved templates, images and documents, interactive replies with buttons or lists, location pins, contact cards, emoji reactions. A second group handles media: upload a file, resolve a media_id to a download URL, delete an asset. Templates and the business profile are covered too.
Auth is a Bearer token against the Graph API. You need a permanent system-user token from Meta Business Manager, because user tokens expire and will break production. Three environment variables are required: WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID and WHATSAPP_BUSINESS_ACCOUNT_ID. The Graph version is optional. Phone numbers go in E.164 without the leading +.
Messaging rules matter here. For 24 hours after the user's last message you can send anything; past that window only an approved template goes through. Templates are created first and then wait on Meta's review. Uploaded media expires after roughly 30 days, so catalog assets are better kept as a link or re-uploaded. This server targets merchants with an approved WhatsApp Business Account who want Meta-direct pricing and no intermediary fees.
What it helps with
- send a text or template to a customer from the agent
- upload an image once and reuse its
media_id - build an interactive message with confirm and cancel buttons
- submit a template and wait for Meta approval
- mark an incoming message as read
Example prompts for the agent
- Send the
order_confirmedtemplate to5511999999999in Portuguese - Upload
catalog.pngand reply with it to the last message - Build an interactive message with Confirm and Cancel reply buttons
How to install mcp-whatsapp-cloud
Platform CLI
claude mcp add --env WHATSAPP_ACCESS_TOKEN=<WHATSAPP_ACCESS_TOKEN> --env WHATSAPP_PHONE_NUMBER_ID=<WHATSAPP_PHONE_NUMBER_ID> --env WHATSAPP_BUSINESS_ACCOUNT_ID=<WHATSAPP_BUSINESS_ACCOUNT_ID> --env WHATSAPP_GRAPH_VERSION=<WHATSAPP_GRAPH_VERSION> --transport stdio whatsapp-cloud -- npx -y @codespar/mcp-whatsapp-cloudReplace <…> with your own values
Platform CLI
codex mcp add whatsapp-cloud --env WHATSAPP_ACCESS_TOKEN=<WHATSAPP_ACCESS_TOKEN> --env WHATSAPP_PHONE_NUMBER_ID=<WHATSAPP_PHONE_NUMBER_ID> --env WHATSAPP_BUSINESS_ACCOUNT_ID=<WHATSAPP_BUSINESS_ACCOUNT_ID> --env WHATSAPP_GRAPH_VERSION=<WHATSAPP_GRAPH_VERSION> -- npx -y @codespar/mcp-whatsapp-cloudReplace <…> with your own values
Config file
{
"mcpServers": {
"whatsapp-cloud": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-whatsapp-cloud"
],
"env": {
"WHATSAPP_ACCESS_TOKEN": "<WHATSAPP_ACCESS_TOKEN>",
"WHATSAPP_PHONE_NUMBER_ID": "<WHATSAPP_PHONE_NUMBER_ID>",
"WHATSAPP_BUSINESS_ACCOUNT_ID": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"WHATSAPP_GRAPH_VERSION": "<WHATSAPP_GRAPH_VERSION>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"whatsapp-cloud": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-whatsapp-cloud"
],
"env": {
"WHATSAPP_ACCESS_TOKEN": "<WHATSAPP_ACCESS_TOKEN>",
"WHATSAPP_PHONE_NUMBER_ID": "<WHATSAPP_PHONE_NUMBER_ID>",
"WHATSAPP_BUSINESS_ACCOUNT_ID": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"WHATSAPP_GRAPH_VERSION": "<WHATSAPP_GRAPH_VERSION>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e WHATSAPP_ACCESS_TOKEN=<WHATSAPP_ACCESS_TOKEN> -e WHATSAPP_PHONE_NUMBER_ID=<WHATSAPP_PHONE_NUMBER_ID> -e WHATSAPP_BUSINESS_ACCOUNT_ID=<WHATSAPP_BUSINESS_ACCOUNT_ID> -e WHATSAPP_GRAPH_VERSION=<WHATSAPP_GRAPH_VERSION> whatsapp-cloud npx -y @codespar/mcp-whatsapp-cloudReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-whatsapp-cloud
How do I install mcp-whatsapp-cloud in Claude Code?
Run `claude mcp add mcp-whatsapp-cloud -e WHATSAPP_ACCESS_TOKEN=<WHATSAPP_ACCESS_TOKEN> -e WHATSAPP_PHONE_NUMBER_ID=<WHATSAPP_PHONE_NUMBER_ID> -e WHATSAPP_BUSINESS_ACCOUNT_ID=<WHATSAPP_BUSINESS_ACCOUNT_ID> -- npx -y @codespar/mcp-whatsapp-cloud`. Fill in your own token and IDs.
What does mcp-whatsapp-cloud do?
It is an MCP server for Meta's WhatsApp Cloud API. It lets an agent send messages, media and templates, and manage the business profile and phone numbers.
Why does my message fail outside the 24-hour window?
You have 24 hours after the user's last message to send any type. After that the Cloud API only accepts an approved template, so use send_template_message.
