🟢 WA MCP

The first WhatsApp integration built natively for AI Agents.
Full MCP server exposing WhatsApp as discoverable tools, resources, and real-time notifications.

Quick Start • Features • Tools • Architecture • Configuration • Docker • Contributing

🤖 What is WA MCP?

WA MCP is a WhatsApp MCP server built with TypeScript that gives AI agents full access to WhatsApp through the Model Context Protocol. It supports both Baileys (WhatsApp Web) and Meta Cloud API as dual-channel backends, deployable with Docker in a single command.

Your agent connects once and auto-discovers 63 tools, 10 resources, and 12 real-time events — zero configuration, zero REST wrappers, zero glue code.

Your AI Agent ←→ MCP Protocol ←→ WA MCP ←→ WhatsApp

Instead of writing HTTP clients, parsing webhook payloads, and mapping endpoints to tools manually — your agent just connects and goes. Works out of the box with Claude, Google ADK, LangChain, and any MCP-compatible AI agent framework.

💡 MCP (Model Context Protocol) is the open standard for connecting AI agents to tools and data. WA MCP speaks MCP natively via Streamable HTTP and stdio transports.

🚀 Quick Start

One command with Docker

docker compose up

That's it. WA MCP + Redis, ready on http://localhost:3000/mcp.

Or run locally

# Prerequisites: Node.js >= 22, Redis running
npm install
cp .env.example .env

# Development (stdio transport)
npm run dev

# Production (HTTP transport)
npm run build && npm start

Connect your agent

from google.adk.tools.mcp_tool import McpToolset

tools = McpToolset(url="http://localhost:3000/mcp")

# Agent auto-discovers 63 WhatsApp tools
# wa_create_instance, wa_send_text, wa_send_image, ...

from langchain_mcp import McpToolkit

toolkit = McpToolkit(server_url="http://localhost:3000/mcp")
tools = toolkit.get_tools()

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["path/to/wa-mcp/dist/index.js"],
      "env": {
        "WA_TRANSPORT": "stdio",
        "WA_REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}

✨ Features

🛠️ Tools

WA MCP exposes 63 tools across 9 domains. All tools use the wa_ prefix.

📖 Resources

Resources expose read-only WhatsApp state via whatsapp:// URIs:

📡 Real-time Notifications

Events are pushed to agents via SSE (Server-Sent Events):

🏗️ Architecture

┌─────────────────────────────────────────────┐
│              AI Agent Runtime               │
│    (Google ADK, Claude, LangChain, ...)     │
└──────────────────┬──────────────────────────┘
                   │  MCP Streamable HTTP
┌──────────────────▼──────────────────────────┐
│              WA MCP Server                  │
│                                             │
│  ┌────────────────────────────────────────┐ │
│  │  Layer 1 — MCP Transport (HTTP/stdio) │ │
│  ├────────────────────────────────────────┤ │
│  │  Layer 2 — MCP Core                   │ │
│  │  63 Tools │ 10 Resources │ 12 Events  │ │
│  ├────────────────────────────────────────┤ │
│  │  Layer 3 — Services                   │ │
│  │  Instance Manager │ Queue │ Dedup     │ │
│  ├────────────────────────────────────────┤ │
│  │  Layer 4 — Channel Abstraction        │ │
│  │  ┌──────────────┐ ┌────────────────┐  │ │
│  │  │   Baileys    │ │   Cloud API    │  │ │
│  │  │  (WebSocket) │ │    (HTTPS)     │  │ │
│  │  └──────────────┘ └────────────────┘  │ │
│  └────────────────────────────────────────┘ │
│       SQLite (Drizzle)    BullMQ (Redis)    │
└─────────────────────────────────────────────┘
                   │
                   ▼  WebSocket / HTTPS
          WhatsApp Servers

Dual-Channel Design

Both backends implement the same ChannelAdapter interface. Your agent doesn't know or care which one is active — the tools work identically.

⚙️ Configuration

Copy .env.example to .env and configure:

🐳 Docker

Production

docker compose up -d

Services:

• wa-mcp — The MCP server on port 3000
• redis — BullMQ backend with AOF persistence

Health Check

curl http://localhost:3000/health

{
  "status": "ok",
  "uptime": 3600,
  "instances": { "total": 3, "connected": 2, "disconnected": 1 },
  "version": "1.0.0"
}

Resource Requirements

📁 Project Structure

src/
├── index.ts                     # Entry point (HTTP/stdio)
├── constants.ts                 # Defaults and limits
├── server/mcp.ts                # MCP server setup
├── tools/                       # 🔧 63 MCP tools (9 files)
├── resources/                   # 📖 10 MCP resources (8 files)
├── notifications/events.ts      # 📡 12 event types
├── channels/
│   ├── channel.interface.ts     # ChannelAdapter contract
│   ├── baileys/                 # Baileys implementation
│   └── cloud-api/               # Cloud API implementation
├── services/
│   ├── instance-manager.ts      # Instance lifecycle
│   ├── message-queue.ts         # BullMQ rate limiting
│   ├── dedup.ts                 # Message deduplication
│   └── media.ts                 # Media handling
├── db/
│   ├── schema.ts                # Drizzle table definitions
│   └── client.ts                # SQLite connection
├── schemas/                     # Zod validation (9 files)
└── types/                       # TypeScript definitions

🗺️ Roadmap

• Phase 1 — Foundation: Baileys adapter, text messaging, QR auth, instance management
• Phase 2 — Full messaging: all media types, dedup, reactions, edits, forwards
• Phase 3 — Groups, contacts, profile, status/stories, newsletters
• Phase 4 — Cloud API adapter: dual-channel unified interface
• Phase 5 — Hardening: error recovery, CI/CD, tests, docs, v1.0 release
• Phase 6 — Baileys v7 upgrade, LID support, contact sync, message persistence

🤝 Contributing

Contributions are welcome! Here's how the codebase is organized:

1. One file per domain — tools, resources, schemas, and channels each have domain-specific files
2. Zod schemas for everything — all tool inputs are validated with strict Zod schemas in src/schemas/
3. Both adapters — new features should be implemented in Baileys and stubbed in Cloud API
4. Layered architecture — tools → services → channels. No cross-layer imports.
5. Structured logging — use Pino, never console.log

# Development
npm run dev          # Start with stdio transport
npm run build        # Type-check + compile
npx tsc --noEmit     # Type-check only

📄 License

MIT — do whatever you want.

Built for the agentic era.
Stop writing REST wrappers. Let your agent discover WhatsApp.