<div align="center">

wamcp

</div>

---

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

| Feature | Description | |---|---| | 🔌 MCP-native | Exposes WhatsApp over the Model Context Protocol using Streamable HTTP and stdio transports, so any MCP-compatible agent can connect without custom glue. | | 📱 Dual-channel backends | Choose Baileys (WhatsApp Web) or the Meta Cloud API behind a single unified interface. | | 🧰 61 tools | A broad, wa_-prefixed tool surface spanning messaging, chats, groups, contacts, profile, presence, and more. | | 📚 10 resources | Discoverable MCP resources for reading WhatsApp state alongside tool calls. | | 📡 12 real-time events | Push notifications for incoming messages, presence/typing, connection changes, and other live activity. | | 🔄 Multi-instance | Drive multiple WhatsApp numbers from one server process. | | 📨 Rich messaging | Text, media, documents, polls, reactions, replies, edits, deletes, and view-once messages. | | 👥 Group management | List groups, inspect participants, and manage membership and settings. | | 👤 Contacts & profile | Number checks, contact search, blocking, and profile/privacy operations. | | 🔁 Auto-reconnect | Resilient session handling that recovers from dropped connections. | | 🗃️ Persistent storage | Sessions, messages, and metadata survive restarts. | | 🧩 TypeScript | Fully typed codebase for safe integration and extension. |

Transports

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

Backend selection

| Backend | Use when | |---|---| | Baileys | You want WhatsApp Web-style access without a Meta business account. | | Cloud API | You already have Meta Cloud API credentials and want the official hosted channel. |

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:

| Capability | Count | What the agent sees | |---|---|---| | Tools | 61 | Callable actions like sending a message, listing groups, reacting, checking a number | | Resources | 10 | Readable state such as chats, contacts, groups, and instance status | | Events | 12 | Real-time notifications pushed over the connection (incoming message, typing, connection changes, and more) |

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:

| Channel | Session | Best for | |---|---|---| | Baileys | WhatsApp Web link (QR / pairing code) | Personal numbers, full feature surface | | Cloud API | Meta-issued token + phone number ID | Business accounts, official rate limits |

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

| Transport | When to use | |---|---| | Streamable HTTP | Server deployed once, agents connect remotely; supports SSE for events | | stdio | Agent and server live on the same machine; the agent spawns the server |

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

| Source | How to provide | Notes | |---|---|---| | Environment variables | .env file or process environment | Prefix WA_; recommended for Docker | | JSON config file | WA_CONFIG_FILE=/path/to/config.json | Useful for multi-instance and per-instance overrides | | CLI flags | --transport, --port, --config | Highest precedence; useful for local runs |

Core variables

| Variable | Default | Purpose | |---|---|---| | WA_TRANSPORT | http | MCP transport: http (Streamable HTTP) or stdio | | WA_PORT | 3000 | HTTP listen port (used when WA_TRANSPORT=http) | | WA_HOST | 0.0.0.0 | HTTP bind address | | WA_REDIS_URL | redis://localhost:6379 | Redis connection for BullMQ queues and event fan-out | | WA_DB_PATH | ./data/wamcp.db | SQLite file for sessions, messages, contacts, groups | | WA_LOG_LEVEL | info | debug, info, warn, error | | WA_CONFIG_FILE | — | Path to a JSON config file | | WA_DATA_DIR | ./data | Directory for SQLite, media cache, and session state |

Channel backend

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

| Variable | Default | Purpose | |---|---|---| | WA_CHANNEL | baileys | baileys (WhatsApp Web) or cloud (Meta Cloud API) | | WA_CLOUD_PHONE_NUMBER_ID | — | Required when WA_CHANNEL=cloud | | WA_CLOUD_WABA_ID | — | WhatsApp Business Account ID | | WA_CLOUD_ACCESS_TOKEN | — | Cloud API bearer token (or set per instance with wa_set_cloud_credentials) | | WA_CLOUD_VERIFY_TOKEN | — | Webhook verification token for inbound Cloud API events | | WA_CLOUD_API_VERSION | — | Meta Graph API version to target | | WA_SESSION_DIR | ./data/sessions | Baileys auth state directory (per instance) |

Multi-instance

Instances are created at runtime with wa_create_instance. This setting only caps how many can coexist.

| Variable | Default | Purpose | |---|---|---| | WA_MAX_INSTANCES | 10 | Upper bound on concurrent WhatsApp instances |

Per-instance credentials and channel selection can also be supplied in the config file:

{
  "instances": [
    {
      "id": "support",
      "channel": "baileys"
    },
    {
      "id": "sales",
      "channel": "cloud",
      "cloud": {
        "phoneNumberId": "env:WA_SALES_PHONE_NUMBER_ID",
        "wabaId": "env:WA_SALES_WABA_ID",
        "accessToken": "env:WA_SALES_ACCESS_TOKEN"
      }
    }
  ]
}

Values of the form env:NAME are resolved from the process environment at startup, so secrets do not have to live in the JSON file.

Rate limiting

Outbound messaging is queued through BullMQ to reduce ban risk. Tune the limits if your workload is well below the defaults.

| Variable | Default | Purpose | |---|---|---| | WA_RATE_LIMIT_BAILEYS_PER_MIN | 20 | Outbound message cap for Baileys instances | | WA_RATE_LIMIT_CLOUD_PER_MIN | 80 | Outbound message cap for Cloud API instances | | WA_RATE_LIMIT_BURST | 5 | Extra allowance above the per-minute rate | | WA_QUEUE_CONCURRENCY | 1 | Worker concurrency for the outbound queue |

Gated writes

Some tools mutate WhatsApp app state (labels, communities, newsletters, catalog, certain privacy settings). These are disabled unless explicitly enabled.

| Variable | Default | Purpose | |---|---|---| | WA_APP_STATE_WRITES_ENABLED | false | Enable gated app-state write tools | | WA_TOOL_ALLOWLIST | — | Comma-separated wa_* tools to expose; when set, all others are hidden | | WA_TOOL_DENYLIST | — | Comma-separated wa_* tools to hide |

Audio transcription (optional)

| Variable | Purpose