--- title: "WhatsMCP — MCP Server for Real WhatsApp Numbers" description: "A hosted Model Context Protocol server that gives your AI agent a real WhatsApp account: messages, contacts, groups, calls, media and webhooks." url: "https://whatsmcp.com/" --- MCP-Server # 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. [Get an API key](https://app.whatsmcp.com/console/register) [Talk to us](https://whatsmcp.com/contact) mcp.json ``` { "mcpServers": { "wamcp": { "type": "http", "url": "https://app.whatsmcp.com/mcp", "headers": { "Authorization": "Bearer wamcp_live_…" } } } } ``` How-it-works ## Three hops from prompt to WhatsApp. MCP client Claude Desktop, Cursor, custom agent JSON-RPC WhatsMCP server Protocol translation device session WhatsApp Real devices & networks ### 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. Tools ## 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` Egress ## 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. [Ask us to point an account at your endpoint](https://whatsmcp.com/contact) egress ``` # 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 ``` Console ## 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 app.whatsmcp.com/console Fleet Pair device API keys Webhooks Usage Help Accounts 12 online Messages 4,192 API calls 38k | Number | Mode | State | | --- | --- | --- | | +1 (415) 555-2671 | Companion | connected | | +44 7700 900077 | Companion | connected | Console ## 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. app.whatsmcp.com/console/pair ![The WhatsMCP console's Pair device page: a QR code to scan from WhatsApp's Linked devices screen, above a four-stage progress indicator reading code, scanned, syncing, ready.](https://whatsmcp.com/_astro/console-pair-device.DTCyWKD0_epE5e.webp) Connect ## Connected in four steps. Pick your client for the first step. The other three are the same everywhere. 1 ### 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](https://whatsmcp.com/docs/mcp#connect-your-client). 2 ### 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…"} ``` 3 ### 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…"} ``` Control-Plane ## 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 Accounts online 12/12 Calls today 1,492 Uptime 99.9% | Number | Mode | Status | | --- | --- | --- | | +1 (415) 555-2671 | Companion | connected | | +44 7700 900077 | Companion | connected | FAQ ## 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. Community ## Trusted by infrastructure engineers. Alex Morgan > “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.” AI AGENT INTEGRATION Daniel Brooks > “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.” MCP PROTOCOL Chris Bennett > “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.” RAPID PROTOTYPING Michael Reed > “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.” MESSAGE POLLING James Carter > “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.” AGENT COMMUNICATION Ryan Mitchell > “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.” SIMPLE SETUP Ethan Parker > “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.” API + CONSOLE Noah Williams > “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.” REAL WORKFLOWS Oliver Hayes > “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.” WEBHOOKS Lucas Anderson > “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.” FASTER ITERATION ## Give your agent a number. [Get an API key](https://app.whatsmcp.com/console/register) Free tier includes 1 concurrent device session.