WA MCP
by delltrak
README.md
<p align="center">
<img src="https://img.shields.io/badge/WhatsApp-25D366?style=for-the-badge&logo=whatsapp&logoColor=white" alt="WhatsApp" />
<img src="https://img.shields.io/badge/MCP-000000?style=for-the-badge&logo=anthropic&logoColor=white" alt="MCP" />
<img src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" />
<img src="https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker" />
</p>
<h1 align="center">🟢 WA MCP</h1>
<p align="center">
<strong>The first WhatsApp integration built natively for AI Agents.</strong>
<br />
<em>Full MCP server exposing WhatsApp as discoverable tools, resources, and real-time notifications.</em>
</p>
<p align="center">
<a href="#-quick-start">Quick Start</a> •
<a href="#-features">Features</a> •
<a href="#-tools">Tools</a> •
<a href="#-architecture">Architecture</a> •
<a href="#%EF%B8%8F-configuration">Configuration</a> •
<a href="#-docker">Docker</a> •
<a href="#-contributing">Contributing</a>
</p>
<p align="center">
<a href="https://github.com/delltrak/wamcp/actions/workflows/ci.yml"><img src="https://github.com/delltrak/wamcp/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
<img src="https://img.shields.io/github/license/delltrak/wamcp?style=flat-square" alt="License" />
<img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen?style=flat-square" alt="Node" />
<img src="https://img.shields.io/badge/MCP-Streamable%20HTTP-blue?style=flat-square" alt="Transport" />
</p>
---
## 🤖 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](https://modelcontextprotocol.io). 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
```bash
docker compose up
```
That's it. WA MCP + Redis, ready on `http://localhost:3000/mcp`.
### Or run locally
```bash
# 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
<details>
<summary>🐍 Google ADK (Python)</summary>
```python
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, ...
```
</details>
<details>
<summary>🦜 LangChain</summary>
```python
from langchain_mcp import McpToolkit
toolkit = McpToolkit(server_url="http://localhost:3000/mcp")
tools = toolkit.get_tools()
```
</details>
<details>
<summary>💻 Claude Desktop</summary>
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"whatsapp": {
"command": "node",
"args": ["path/to/wa-mcp/dist/index.js"],
"env": {
"WA_TRANSPORT": "stdio",
"WA_REDIS_URL": "redis://localhost:6379"
}
}
}
}
```
</details>
---
## ✨ Features
| | Feature | Description |
| --- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
| 🔌 | **MCP-native** | Streamable HTTP + stdio transports. No REST, no webhooks. |
| 📱 | **Dual-channel** | Baileys (WhatsApp Web) + Meta Cloud API — same interface. |
| 🔄 | **Multi-instance** | Run 1–50 WhatsApp numbers from a single server. |
| 📨 | **Full messaging** | Text, images, video, audio, documents, polls, reactions, replies, forwards, edits, deletes, view-once. |
| 👥 | **Groups** | Create, manage members, promote/demote admins, settings, invite links, join requests, ephemeral messages. |
| 👤 | **Contacts & Profile** | Number check, block/unblock, business profiles, privacy, status updates. |
| 📡 | **Real-time events** | 12 notification types via SSE: messages, typing, groups, calls, connection status. |
| ⚡ | **Rate limiting** | BullMQ queues prevent WhatsApp bans (20 msg/min Baileys, 80 msg/min Cloud). |
| 🔁 | **Auto-reconnect** | Automatic reconnection with exponential backoff. |
| 🗃️ | **Persistent** | SQLite storage for sessions, messages, contacts, groups. |
| 🐳 | **Single container** | `docker compose up` — only Redis as external dependency. |
---
## 🛠️ Tools
WA MCP exposes **63 tools** across 9 domains. All tools use the `wa_` prefix.
<details>
<summary>📋 <strong>Instance Management</strong> (8 tools)</summary>
| Tool | Description |
| -------------------------- | -------------------------------- |
| `wa_create_instance` | Create a new WhatsApp connection |
| `wa_connect_instance` | Connect (generates QR code) |
| `wa_disconnect_instance` | Gracefully disconnect |
| `wa_delete_instance` | Permanently remove instance |
| `wa_restart_instance` | Disconnect + reconnect |
| `wa_get_qr_code` | Get QR as base64 (Baileys) |
| `wa_get_pairing_code` | Get pairing code (Baileys) |
| `wa_set_cloud_credentials` | Set Cloud API token |
</details>
<details>
<summary>💬 <strong>Messaging</strong> (17 tools)</summary>
| Tool | Description |
| ---------------------- | ----------------------- |
| `wa_send_text` | Send text message |
| `wa_send_image` | Send image with caption |
| `wa_send_video` | Send video with caption |
| `wa_send_audio` | Send audio / voice note |
| `wa_send_document` | Send file / document |
| `wa_send_location` | Send GPS location |
| `wa_send_contact` | Send vCard contact |
| `wa_send_poll` | Create a poll |
| `wa_send_reaction` | React with emoji |
| `wa_send_link_preview` | Send URL with preview |
| `wa_forward_message` | Forward a message |
| `wa_edit_message` | Edit sent message |
| `wa_delete_message` | Delete message |
| `wa_pin_message` | Pin a message |
| `wa_send_view_once` | Send view-once media |
| `wa_send_presence` | Show typing / recording |
| `wa_mark_read` | Mark messages as read |
</details>
<details>
<summary>💭 <strong>Chat Management</strong> (6 tools)</summary>
| Tool | Description |
| ----------------- | ------------------------ |
| `wa_get_messages` | Get chat message history |
| `wa_archive_chat` | Archive / unarchive |
| `wa_pin_chat` | Pin / unpin chat |
| `wa_mute_chat` | Mute / unmute |
| `wa_delete_chat` | Delete chat |
| `wa_clear_chat` | Clear chat history |
</details>
<details>
<summary>👥 <strong>Groups</strong> (14 tools)</summary>
| Tool | Description |
| ------------------------------ | ----------------------------- |
| `wa_create_group` | Create group |
| `wa_group_add_participants` | Add members |
| `wa_group_remove_participants` | Remove members |
| `wa_group_promote` | Promote to admin |
| `wa_group_demote` | Demote from admin |
| `wa_group_update_subject` | Change group name |
| `wa_group_update_description` | Change description |
| `wa_group_update_settings` | Change settings |
| `wa_group_leave` | Leave group |
| `wa_group_get_invite_code` | Get invite link |
| `wa_group_revoke_invite` | Revoke invite link |
| `wa_group_join` | Join via invite code |
| `wa_group_toggle_ephemeral` | Toggle disappearing messages |
| `wa_group_handle_request` | Approve / reject join request |
</details>
<details>
<summary>📇 <strong>Contacts</strong> (5 tools)</summary>
| Tool | Description |
| ------------------------- | -------------------------------- |
| `wa_search_contact` | Search contacts by name or phone |
| `wa_check_number_exists` | Check if number is on WhatsApp |
| `wa_block_contact` | Block contact |
| `wa_unblock_contact` | Unblock contact |
| `wa_get_business_profile` | Get business profile |
</details>
<details>
<summary>👤 <strong>Profile</strong> (5 tools)</summary>
| Tool | Description |
| --------------------------- | ----------------------- |
| `wa_update_profile_picture` | Set profile picture |
| `wa_remove_profile_picture` | Remove profile picture |
| `wa_update_profile_name` | Change display name |
| `wa_update_profile_status` | Change status text |
| `wa_update_privacy` | Update privacy settings |
</details>
<details>
<summary>📢 <strong>Status / Stories</strong> (3 tools)</summary>
| Tool | Description |
| ---------------------- | ----------------- |
| `wa_send_text_status` | Post text status |
| `wa_send_image_status` | Post image status |
| `wa_send_video_status` | Post video status |
</details>
<details>
<summary>📰 <strong>Newsletter</strong> (3 tools)</summary>
| Tool | Description |
| ------------------------ | --------------------- |
| `wa_newsletter_follow` | Follow a newsletter |
| `wa_newsletter_unfollow` | Unfollow a newsletter |
| `wa_newsletter_send` | Send to newsletter |
</details>
<details>
<summary>📞 <strong>Calls</strong> (1 tool)</summary>
| Tool | Description |
| ---------------- | -------------------- |
| `wa_reject_call` | Reject incoming call |
</details>
---
## 📖 Resources
Resources expose read-only WhatsApp state via `whatsapp://` URIs:
| URI | Description |
| --------------------------------------------- | ------------------------------ |
| `whatsapp://instances` | List all instances |
| `whatsapp://instances/{id}` | Instance details + queue stats |
| `whatsapp://instances/{id}/contacts` | All contacts |
| `whatsapp://instances/{id}/chats` | Active conversations |
| `whatsapp://instances/{id}/groups` | All groups |
| `whatsapp://instances/{id}/groups/{gid}` | Group metadata |
| `whatsapp://instances/{id}/messages/{chatId}` | Message history |
| `whatsapp://instances/{id}/profile` | Own profile |
| `whatsapp://instances/{id}/privacy` | Privacy settings |
| `whatsapp://instances/{id}/blocklist` | Blocked contacts |
---
## 📡 Real-time Notifications
Events are pushed to agents via SSE (Server-Sent Events):
| Event | Trigger |
| ------------------------------------- | ---------------------------------------------- |
| `whatsapp/message.received` | New incoming message |
| `whatsapp/message.updated` | Status change (sent → delivered → read) |
| `whatsapp/message.deleted` | Message deleted |
| `whatsapp/message.reaction` | Emoji reaction added/removed |
| `whatsapp/message.edited` | Message edited |
| `whatsapp/presence.updated` | Typing / recording / online |
| `whatsapp/chat.updated` | Chat metadata changed |
| `whatsapp/group.updated` | Group info changed |
| `whatsapp/group.participants_changed` | Member add/remove/promote/demote |
| `whatsapp/contact.updated` | Contact info changed |
| `whatsapp/connection.changed` | Instance status change (includes QR as base64) |
| `whatsapp/call.received` | Incoming call |
---
## 🏗️ 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
| | Baileys | Cloud API |
| ---------- | ------------------------ | ------------------------ |
| Protocol | WhatsApp Web (WebSocket) | Meta Official (HTTPS) |
| Auth | QR Code / Pairing Code | Access Token |
| Cost | Free | Per-conversation pricing |
| Compliance | Unofficial | Meta-approved |
| Best for | Dev, testing, low volume | Production, enterprise |
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:
| Variable | Default | Description |
| --------------------------- | ------------------------ | ---------------------------------------- |
| `WA_TRANSPORT` | `http` | `http` (Streamable HTTP) or `stdio` |
| `WA_MCP_API_KEY` | — | Bearer token auth. Unset = no auth (dev) |
| `WA_MCP_PORT` | `3000` | HTTP server port |
| `WA_REDIS_URL` | `redis://localhost:6379` | Redis for BullMQ queues |
| `WA_LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error` |
| `WA_BAILEYS_RATE_LIMIT` | `20` | Messages/min per Baileys instance |
| `WA_CLOUD_RATE_LIMIT` | `80` | Messages/min per Cloud API instance |
| `WA_MESSAGE_RETENTION_DAYS` | `30` | Auto-delete old messages |
| `WA_AUTO_RECONNECT` | `true` | Auto-reconnect on disconnect |
| `WA_MEDIA_CACHE_MAX_MB` | `500` | Media cache size limit |
| `WA_CLOUD_WEBHOOK_SECRET` | — | Meta webhook verification |
| `WA_CLOUD_WEBHOOK_PORT` | `3001` | Webhook receiver port |
| `WA_VERSION_CHECK` | `true` | Daily WhatsApp Web version check |
---
## 🐳 Docker
### Production
```bash
docker compose up -d
```
Services:
- **wa-mcp** — The MCP server on port `3000`
- **redis** — BullMQ backend with AOF persistence
### Health Check
```bash
curl http://localhost:3000/health
```
```json
{
"status": "ok",
"uptime": 3600,
"instances": { "total": 3, "connected": 2, "disconnected": 1 },
"version": "1.0.0"
}
```
### Resource Requirements
| Instances | RAM | CPU | Disk |
| --------- | ------ | -------- | ----- |
| 1–5 | 256 MB | 0.5 vCPU | 1 GB |
| 5–20 | 512 MB | 1 vCPU | 5 GB |
| 20–50 | 1 GB | 2 vCPU | 10 GB |
---
## 📁 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
- [x] **Phase 1** — Foundation: Baileys adapter, text messaging, QR auth, instance management
- [x] **Phase 2** — Full messaging: all media types, dedup, reactions, edits, forwards
- [x] **Phase 3** — Groups, contacts, profile, status/stories, newsletters
- [x] **Phase 4** — Cloud API adapter: dual-channel unified interface
- [x] **Phase 5** — Hardening: error recovery, CI/CD, tests, docs, v1.0 release
- [x] **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`
```bash
# 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.
---
<p align="center">
<strong>Built for the agentic era.</strong>
<br />
<em>Stop writing REST wrappers. Let your agent discover WhatsApp.</em>
</p>
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues