Put an AI agent on a real WhatsApp number.
Expose regular WhatsApp accounts to your LLM agents over JSON-RPC. A complete Model Context Protocol server that turns phone numbers into addressable tools.
{ "mcpServers": { "wamcp": { "type": "http", "url": "https://app.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.
42 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, and fetch the attachments a message carried.
wa_send_message wa_list_messages wa_get_chat wa_get_media Message operations
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
List the address book, search it by name or number, and look up who a number is on WhatsApp.
wa_list_contacts wa_search_contacts wa_get_profile Blocklist
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_unblock_contact wa_list_blocked Groups & channels
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
Add and remove members, grant and revoke admin, rename, lock settings, make it announce-only, or reissue the invite link.
wa_add_participants wa_remove_participants wa_promote_participants wa_demote_participants wa_set_group_name wa_set_group_description wa_set_group_locked wa_set_group_announce wa_get_group_invite_link Accounts & plan
Pair a number by QR, poll the pairing, list sessions, unpair, and read your plan with its usage so far.
wa_list_accounts wa_pair_account wa_pair_status wa_unpair_account wa_get_plan wa_get_version Calls
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 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.
By default an account's session leaves through our egress. Nominate your own instead — a SOCKS5 proxy or a WireGuard peer — and that account's WhatsApp traffic exits where you say it does.
- 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://app.whatsmcp.com/mcp > /mcp wamcp — Authenticate → browser → connected (42 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://app.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://app.whatsmcp.com/mcp Authentication: OAuth
Codex — one command to add it, one to sign in. Or write the same server into ~/.codex/config.toml with auth = "oauth".
codex mcp add wamcp --url https://app.whatsmcp.com/mcp codex mcp login wamcp wamcp — 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.
> 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…"}
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
- • Prometheus metrics export
- • 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 connects as a linked device — the same mechanism as WhatsApp Web — and is not affiliated with, authorized by, or endorsed by Meta or WhatsApp.
Is this a real WhatsApp account, or a sandbox?
A real number. Your phone stays the primary device and can stay in your pocket afterwards — WhatsMCP links to it the same way WhatsApp Web does, and you can unlink it at any time from the handset's Linked devices screen or with wa_unpair_account.
What can my AI agent actually do through it?
42 tools spanning messaging, message edits and reactions, contacts and profile lookup, the blocklist, groups and channels with full admin, calls, and webhooks. Which ones appear in tools/list depends on your plan — 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?
By scanning 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.
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. WhatsMCP is an unofficial integration, so — like any WhatsApp automation — a number can be blocked; there's no guarantee against that, only honest handling when it happens.
What's included in the free tier?
Sign-up is self-serve and free — no card, no sales call. The free plan includes one concurrent device session; higher tiers unlock capabilities like webhooks and higher send caps.
Can I run WhatsMCP on my own infrastructure?
No — it's a hosted service only. You point your MCP client at https://app.whatsmcp.com/mcp with an API key; there is no local process or container to run yourself.
Unofficial, and honest about it.
WhatsMCP speaks the WhatsApp protocol directly. It is not affiliated with Meta, and running it is outside WhatsApp's terms of service. Numbers can be blocked. Think hard before you put a number you care about on it — and don't spam.
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 tier includes 1 concurrent device session.