wamcp

wamcp is a WhatsApp MCP server that connects AI agents to WhatsApp through the Model Context Protocol, exposing 61 tools, 10 resources, and 12 real-time events that agents discover automatically on connect. It supports both Baileys (WhatsApp Web) and the Meta Cloud API behind a single interface, so the same agent code works against either backend. It's built for developers wiring WhatsApp into MCP-compatible frameworks like Claude, LangChain, or Google ADK without writing REST wrappers or webhook parsers. Written in TypeScript with Docker deployment and Redis-backed rate limiting to keep high-volume messaging within WhatsApp's limits.

Features

Transports

Agent  ──MCP (Streamable HTTP | stdio)──▶  wamcp  ──▶  Baileys / Cloud API  ──▶  WhatsApp

Backend selection

Tool surface at a glance

wa_* tools grouped by domain:
  • Messaging      • Chats          • Groups
  • Contacts       • Profile        • Presence
  • Media          • Reactions      • Polls
  • ...            (61 tools total)

• Agent-first design — every capability is a discoverable MCP tool or resource, not a hand-rolled REST wrapper.
• Live by default — 12 real-time events keep agent state in sync without polling.
• One interface, two channels — swap Baileys for Cloud API without rewriting agent logic.

How it works

wamcp sits between your AI agent and WhatsApp as a single MCP endpoint. Your agent speaks the Model Context Protocol — either over Streamable HTTP or over stdio — and the server does the rest: it manages the WhatsApp session, queues outgoing sends, persists what it sees, and pushes real-time signals back to the agent as they arrive.

┌──────────────┐   MCP (HTTP / stdio)   ┌───────────┐   Baileys  ┌────────────┐
│   AI Agent   │ ◄────────────────────► │   wamcp   │ ◄────────► │ WhatsApp   │
│ (Claude, ...)│   tools / resources    │  server   │   Cloud API│ (anything) │
└──────────────┘   events / SSE         └─────┬─────┘            └────────────┘
                                               │
                                        ┌──────┴──────┐
                                        │  Storage    │
                                        │  (sessions, │
                                        │  messages)  │
                                        └─────────────┘

1. The agent connects

wamcp presents itself as an MCP server. On connect, the client discovers the full surface automatically:

No generated client library, no endpoint mapping. The agent asks what's available and gets the catalog.

2. Channel selection

wamcp supports two WhatsApp backends behind one interface. Pick the one that fits your deployment:

Both are driven through the same wa_* tool names, so an agent's tool calls stay stable when you switch channels. Where a capability exists only on one channel (e.g. QR linking on Baileys), the other channel returns a clear unsupported-operation error rather than failing silently.

3. A tool call travels through the stack

Agent calls wa_send_text({ chatId, text })
      │
      ▼
┌─────────────────┐   validate input against the tool schema
│  MCP handler    │
└────────┬────────┘
         ▼
┌─────────────────┐   authenticate + normalize to a channel-neutral form
│  Channel layer  │
└────────┬────────┘
         ▼
┌─────────────────┐   enqueue the outbound action (rate-limited)
│  Send queue     │
└────────┬────────┘
         ▼
┌─────────────────┐   deliver via Baileys or Cloud API
│  WhatsApp       │
└────────┬────────┘
         ▼
   response returned to agent (delivery status, message ID, ...)

Outgoing messages go through a queue so bursts are throttled to safe rates instead of tripping WhatsApp's abuse detection. The agent gets back a structured result — not a fire-and-forget acknowledgment.

4. Inbound messages and events

When something happens on the WhatsApp side, wamcp turns it into one of two things for the agent:

• Persisted state — messages, contacts, and group metadata are written to local storage so later reads (wa_get_messages, wa_search_messages, resource reads) return real history rather than requiring a round trip to WhatsApp.
• A real-time event — emitted over the MCP connection so the agent can react immediately without polling.

Incoming audio can optionally be transcribed, and outgoing voice notes can optionally be synthesized, both gated behind configuration so the default path stays dependency-light.

5. One server, many instances

A single wamcp process can host multiple WhatsApp instances — separate numbers or separate channels — each with its own session and its own state. Every tool and resource takes an instance identifier (implicit or explicit depending on call shape), so your agent manages them all through the same connection.

Transport and lifecycle

Sessions are durable: Baileys credentials persist across restarts, so a reconnecting instance resumes without re-pairing. When the WhatsApp connection drops, the server reconnects with exponential backoff on its own — the agent only needs to listen for connection events if it wants to surface them to the user.

Configuration

WA MCP is configured through environment variables, a JSON config file passed via WA_CONFIG_FILE, or CLI flags. Environment variables take precedence over the config file, and CLI flags take precedence over both. For the complete list of supported keys, see the API reference.

Configuration sources

Core variables

Channel backend

Select the backend used to talk to WhatsApp. Both backends expose the same MCP tool surface.