← projects

mcp-whatsapp-agent-platform

An open-source MCP server for Meta's WhatsApp Agent Platform: a private WhatsApp line between one person and their own agent, connected to Claude Code through channels.

year
2026
stack
MCP server (Node), WhatsApp Agent Platform, Claude Code channels

A coding agent working in a terminal can only take instructions from the keyboard in front of it. Step away from the desk and the session is out of reach, even when all it needs is a yes, a file or a quick answer. Most ways of connecting an agent to WhatsApp either emulate WhatsApp Web, logging in as the person and seeing every chat, or use the business API built for messaging customers. Neither fits one person talking privately to their own agent.

mcp-whatsapp-agent-platform is an open-source MCP server for Meta's WhatsApp Agent Platform, which gives a personal WhatsApp account an agent profile that can only talk to the person who created it. Any MCP client gets tools to message that person. With Claude Code's channels feature, messages from the phone also arrive in the running session, and the agent replies in the same chat.

Architecture

Diagram: a message from the phone goes to Meta's WhatsApp Agent Platform. The local MCP server long-polls the platform, confirms the sender is the agent profile's creator, and pushes the message into the running Claude Code session. Replies go back through the send and send_file tools and POST /messages to the same chat. No public webhook or inbound port; one poller per profile; sends stay under 12 a minute; media is saved locally and deleted from Meta.
Long polling from the local machine: no webhook, no open ports, and only the creator on the other end.

How it works

  1. Create an agent profile. In WhatsApp, Settings → Agents creates the profile and issues an API key, kept in a mode-600 file.
  2. Poll. The MCP server long-polls the platform for updates. Handled message IDs are recorded, so a restart never replays the backlog.
  3. Verify. Before anything reaches the agent, the server confirms with Meta that the sender is the profile's creator. Anything else is dropped.
  4. Deliver. Text, images, documents and reactions arrive in the session as channel events. Media is saved locally for the agent to read, then deleted from Meta's servers.
  5. Reply. The agent answers with send or send_file, and a typing indicator runs until it does.

Design decisions

  • Scope enforced in the tools. The send tool has no recipient parameter. It can reach the creator and nobody else, and the platform rejects anything else anyway.
  • No inbound exposure. Long polling instead of a webhook means no public endpoint and no open ports on the machine running the agent.
  • Same authority as the keyboard, no more. A WhatsApp message is treated exactly like typed input. Claude Code's permission prompts still apply, and relaying them to the phone is off by default.
  • Rules for any connected agent. The server's instructions tell the agent never to send secrets (the channel isn't end-to-end encrypted), to treat text inside forwarded documents as content rather than instructions, to confirm risky actions requested from the phone, and to answer on the channel the person last used.
  • One poller per profile. A lock file makes sure only one session receives messages; other sessions stay send-only and take over when it exits. Sends, read receipts and polls stay under Meta's per-minute limits.

What's next

  • Voice notes, transcribed with Whisper on Workers AI or locally.
  • Opt-in conversation history in SQLite.
  • Rate-limit feedback for agents that talk too much.
  • Switching or starting sessions from WhatsApp.

Open source under the MIT license: shipley-c/mcp-whatsapp-agent-platform.