Put an AI agent on a real WhatsApp number.
Expose WhatsApp numbers to your LLM agents over JSON-RPC. A complete Model Context Protocol server that turns phone numbers into addressable tools — a Personal number linked as a device, or a Business (official) number on Meta’s Cloud API.
{ "mcpServers": { "wamcp": { "type": "http", "url": "https://api.whatsmcp.com/mcp", "headers": { "Authorization": "Bearer wamcp_live_…" } } } }
Three hops from prompt to WhatsApp.
JSON-RPC over HTTP
Standard MCP transport, so any client that speaks the protocol — Claude, Cursor, your own agent — connects without an SDK.
Cursor-based polling
Fetch new messages reliably with an opaque cursor: no gaps, no duplicates, no WebSocket to babysit in your agent runtime.
Webhooks for push
Optional delivery of incoming events to your own backend for asynchronous processing.
One toolbelt for the whole account.
46 tools over one endpoint. Which of them appear in tools/list depends on your plan — a tool your plan does not include is absent, not present and refusing.
Messaging
Send text, images, documents and voice notes, page history with a cursor, fetch any one message by its id, and download the attachments a message carried. On a Personal number, pull older history from the phone on demand.
wa_send_message wa_list_messages wa_get_chat wa_get_message wa_get_media wa_load_history Message operations
Personal numbers only
Act on a message already sent or received: react, edit inside the window, revoke, or announce that you are typing.
wa_react wa_edit_message wa_delete_message wa_set_presence Contacts & profiles
Personal numbers only
List the address book or search it by name or number, and look up who a number is on WhatsApp.
wa_list_contacts wa_get_profile Blocklist
Personal numbers only
Block and unblock a contact, and read back who an account has blocked — with the name and country, not just a number.
wa_block_contact wa_list_blocked Groups & channels
Personal numbers only
Create groups, join by invite link, follow channels, list members, and leave again.
wa_create_group wa_list_groups wa_list_group_members wa_join_group wa_leave_chat wa_delete_group wa_follow_channel wa_list_channels Group administration
Personal numbers only
Add and remove members, grant and revoke admin, rename, lock settings, make it announce-only — several settings in one call — or reissue the invite link.
wa_update_participants wa_remove_participants wa_update_group wa_get_group_invite_link Accounts & plan
List your numbers, read each one’s plan with its usage so far, and send the WhatsMCP team a bug report, feature request or feedback. On a Personal number, also pair by QR, poll the pairing, set or remove its profile photo, and unpair.
wa_list_accounts wa_pair_account wa_pair_status wa_unpair_account wa_set_profile_photo wa_get_plan wa_report Calls
Personal numbers only
Export call history, oldest first and paged by cursor — direction, peer, whether it was answered, how long it ran and the codec it used.
wa_list_calls AI voice agents
Personal numbers only
Have an AI voice agent place a WhatsApp call from the number, follow it while it runs, hang it up, and list past calls and the agent presets to start from.
wa_ai_call_start wa_ai_call_get wa_ai_call_hangup wa_ai_list_calls wa_ai_list_presets Message templates
Business (official) numbers only
List, create and delete the pre-approved templates Meta requires to start a conversation, or to reply after the 24-hour window. Meta approves each one.
wa_list_templates wa_create_template wa_delete_template Webhooks
Push inbound messages to your backend instead of polling, and pause delivery without losing the signing secret.
wa_set_webhook wa_get_webhook wa_enable_webhook wa_delete_webhook Choose where the traffic leaves.
For a Personal number, you choose the exit: a SOCKS5 proxy or a WireGuard peer of your own, set per number in the console, and that number's WhatsApp traffic leaves where you say it does. A Business (official) number talks to Meta's Cloud API, so it has no egress to set.
- SOCKS5 with username and password, or a WireGuard peer config.
- Set per account — one number can use your egress while another does not.
- Your network policy and your data-residency rules applied to the session itself.
- Your endpoint, your address: the exit IP does not rotate when ours does.
What it isn't: a way to avoid being blocked. Egress control decides where your traffic goes. It does not change what WhatsApp does with the account, and the terms below still apply.
# SOCKS5 socks5://user:••••••@203.0.113.10:1080 # …or a WireGuard peer [Peer] PublicKey = 8Nd…= Endpoint = 203.0.113.10:51820 AllowedIPs = 0.0.0.0/0
The console behind the API.
Every account, message and key is visible in the console — the same control plane the API drives.
- Pair a number by scanning a QR code
- Track messages sent against your plan's caps
- Browse messages, contacts and call history per number
- Mint and revoke API keys — each shown exactly once
- Point a webhook at your endpoint and watch its recent attempts
| Number | Mode | State |
|---|---|---|
| +1 (415) 555-2671 | Companion | connected |
| +44 7700 900077 | Companion | connected |
Watch a number come online.
Pairing is a QR code and a four-stage run: the handset takes the code, the device logs in and pulls its history, and only then is the number ready to use.
Connected in four steps.
Pick your client for the first step. The other three are the same everywhere.
Add the server
Claude Code — add the endpoint, then run /mcp and sign in through your browser. Nothing to paste.
claude mcp add --transport http wamcp https://api.whatsmcp.com/mcp > /mcp wamcp — Authenticate → browser → connected (46 tools)
Claude Desktop and claude.ai — Settings → Connectors → Add custom connector. Paste the endpoint and leave Authentication on OAuth.
Settings → Connectors → Add custom connector URL https://api.whatsmcp.com/mcp Authentication OAuth ← leave it here, then sign in
ChatGPT — turn on Developer mode under Settings → Security and login, then add the endpoint from Plugins → +. OAuth is the only way in here: the dialog has no field for a header.
Settings → Security and login → Developer mode ✓ Plugins → + → https://api.whatsmcp.com/mcp Authentication: OAuth
Codex — one command adds the server and opens the sign-in in your browser. Run codex mcp login wamcp only to sign in again.
codex mcp add wamcp --url https://api.whatsmcp.com/mcp Detected OAuth support. Starting OAuth flow… Successfully logged in.
Prefer an API key? Every client here also accepts Authorization: Bearer wamcp_live_… — or x-api-key where
the client keeps Authorization for itself. See the connection docs.
Request a pairing code
Start a pairing run. It returns a QR as a base64 PNG, refreshed about every 20 seconds. Connecting a Business (official) number instead? Skip this and the next step — see below.
> wa_pair_account() {"pair_id": "…", "state": "qr", "qr_png_base64": "iVBORw0…"}
Scan with WhatsApp
Link the device from the phone, exactly like WhatsApp Web.
[INFO] device linked: +14155550123 (companion) Send your first message
Your agent can now send and receive on that number.
> wa_send_message({"account_id": "acct_…", "to": "447700900111", "text": "Hello from MCP!"}) {"status": "sent", "message_id": "3EB0…"}
Connect a Business (official) number
A number on Meta’s WhatsApp Cloud API connects from the console, not by QR code. Step 1 — adding the server to your client — is the same, and one connector serves both kinds of number.
- In the console, choose Add a number → Connect with Facebook.
- In Meta’s dialog, pick or create your WhatsApp Business Account and the number.
- The number registers on the Cloud API by itself and appears in your fleet.
-
Start a conversation with a pre-approved template:
wa_send_messagewithtemplateset. Within 24 hours of the customer’s last message you can reply freely.
Connect a Personal or a Business number.
| Personal | Business (official) | |
|---|---|---|
| Setup | Scan a QR code, like WhatsApp Web | Connect with Facebook |
| Messaging and media | ✓ | ✓ |
| Message templates, 24-hour window | — | ✓ |
| Groups, channels, contacts, history import, presence | ✓ | — |
| React, edit, delete, block, profile | ✓ | — |
| SIP voice | ✓ | Not yet |
| Standing with WhatsApp | Outside its terms — a number can be restricted | Official, within Meta’s terms |
| Meta’s fees | None | Meta’s per-message pricing, billed by Meta |
Running a business line? More on the official WhatsApp Business API.
Hear it for yourself
Message our demo number and it calls you back on WhatsApp in a few seconds — a greeting, a beep, and your own voice played straight back.
One number or a fleet — supervised.
Manage every WhatsApp node from a single dashboard. Watch connection state, call and message throughput, and per-account egress.
- • Centralized configuration management
- • Per-number usage against plan caps
- • Webhook event dispatch
| Number | Mode | Status |
|---|---|---|
| +1 (415) 555-2671 | Companion | connected |
| +44 7700 900077 | Companion | connected |
Common questions about the MCP server.
Is WhatsMCP officially affiliated with WhatsApp or Meta?
No. WhatsMCP is not affiliated with, authorized by, or endorsed by Meta or WhatsApp. A Personal number connects as a linked device — the same mechanism as WhatsApp Web; a Business (official) number connects through Meta’s WhatsApp Cloud API.
Is this a real WhatsApp account, or a sandbox?
A real number. A Personal number links the same way WhatsApp Web does: your phone stays the primary device and can stay in your pocket, and you can unlink it at any time from the handset's Linked devices screen or with wa_unpair_account. A Business (official) number is a real number on Meta's Cloud API, in your own WhatsApp Business Account.
What can my AI agent actually do through it?
46 tools spanning messaging, message templates, message edits and reactions, contacts and profile lookup, your own profile photo, the blocklist, groups and channels with full admin, calls, AI voice agents and webhooks. Which ones appear in tools/list depends on your plan and on the kind of number — a tool your plan does not include is absent, not present-and-refusing.
Which MCP clients are supported?
Any client that speaks Streamable HTTP — Claude Code, Claude Desktop, claude.ai, ChatGPT, Codex, and every other remote-capable MCP client. Most sign in with OAuth and need no key at all; clients that cannot do OAuth send an API key in a header instead. A client that only offers "a command to run" does not support remote servers.
How do I connect a WhatsApp number?
A Personal number: scan a QR code, from the console's Pair device page or by calling the wa_pair_account tool directly. The code rotates roughly every 20 seconds, so a stale QR never sits there failing to scan. A Business (official) number: in the console, choose Add a number, then Connect with Facebook.
Does my agent have to poll for new messages, or can it get pushed to?
The server never pushes to your agent — cursor-based polling with wa_list_messages is the source of truth, so a restarted agent resumes from exactly where it left off with no gaps or duplicates. Webhooks are available on paid plans as a push hint on top of that.
Can one workspace see another workspace's messages?
No. Your credential is the workspace — whether it is an API key or an OAuth grant, every tool is scoped to it with no tenant argument to pass, keys are stored hashed and shown once, and a foreign id reads as "no such account" rather than "forbidden", so probing reveals nothing.
What happens if WhatsApp locks or restricts the linked account?
The tools return an account_locked refusal naming the reason rather than failing silently. A Personal number is an unofficial integration, so — like any WhatsApp automation — it can be blocked; there's no guarantee against that, only honest handling when it happens. Business (official) numbers run on Meta's Cloud API under Meta's policies.
What's included in the free tier?
Sign-up is self-serve and free — no card, no sales call. The free plan covers one Personal number; higher tiers unlock capabilities like webhooks and higher send caps. Business (official) plans have no free tier: each starts with a 7-day free trial.
Can I run WhatsMCP on my own infrastructure?
No — it's a hosted service only. You point your MCP client at https://api.whatsmcp.com/mcp with an API key; there is no local process or container to run yourself.
What are message templates?
Pre-approved message formats that Meta requires to start a conversation from a Business (official) number, or to message someone more than 24 hours after they last wrote. List, create and delete them with wa_list_templates, wa_create_template and wa_delete_template; Meta reviews each one. Send one with wa_send_message and its template name. Personal numbers don't use templates.
What is the 24-hour window?
After a customer messages your Business (official) number you can reply freely for 24 hours. Outside that window a free-form message is refused, and only a template can reopen the conversation. Personal numbers have no such window.
Why did a tool refuse with backend_capability?
The number is a Business (official) number and the tool needs something only a Personal number has — groups, contacts, history, reactions and the like. The refusal names the feature, and wa_list_accounts shows each number's backend and features up front.
An independent service
WhatsMCP is not affiliated with or endorsed by Meta. A Personal number connects to WhatsApp directly, as a linked device, and that falls outside WhatsApp’s terms of service, so WhatsApp may restrict a number it sees as misused. We suggest starting with a number you can spare and keeping traffic personal — no bulk or unsolicited messages. A Business (official) number connects through Meta’s WhatsApp Cloud API instead: the officially supported route.
Trusted by infrastructure engineers.
“WhatsMCP makes the connection between AI agents and WhatsApp feel surprisingly simple. We went from setup to sending real messages without having to build a custom integration from scratch.”
“The MCP approach is what really clicked for us. Instead of another proprietary SDK, we can connect our agent directly and start working with WhatsApp through a familiar protocol.”
“Getting a real WhatsApp number connected to an AI agent used to feel like a much bigger engineering project. WhatsMCP turns it into something we can actually prototype in minutes.”
“The cursor-based message polling is a great touch. It gives us a much cleaner way to process incoming conversations without having to constantly worry about missed or duplicated messages.”
“WhatsMCP gave our agents an actual communication channel instead of just another sandbox. Being able to send, receive, search contacts and work with conversations through MCP is incredibly useful.”
“The setup is refreshingly straightforward. Pair the number, connect the MCP endpoint, and the agent can start interacting with WhatsApp. It removes a lot of unnecessary plumbing.”
“We really like that the API and console work together. It gives us the flexibility of automation while still having a place to inspect accounts, messages, usage and connections.”
“WhatsMCP is one of those tools where the value becomes obvious as soon as you try it. Giving an AI agent access to a real WhatsApp account opens up a completely different set of workflows.”
“The webhook support makes it much easier to build asynchronous workflows around incoming WhatsApp messages. We can let the agent handle the conversation while our backend takes care of the rest.”
“Having WhatsApp exposed through standard MCP means we can experiment much faster. We spend less time building integrations and more time figuring out what the agent can actually do.”
Give your agent a number.
Get an API key Open consoleFree plan for Personal numbers · 7-day free trial for Business (official).