whatsapp-mcp
Provides tools for interacting with WhatsApp, including sending and receiving messages, managing chats and contacts, reacting to messages, and downloading media, enabling agents to monitor and participate in conversations.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
WhatsApp MCP Server
WhatsApp as an MCP server. Runs as a long-lived Docker daemon, accessed over HTTPS with Bearer auth, and pushes ntfy notifications when your session needs attention (QR expired, connection dropped). Built on Baileys via the @amiticia/baileys-client wrapper.
Who this is for
You want your WhatsApp account — or several: a personal number and a company line — reachable as a set of tools from Claude Code, Claude Desktop, Cursor, or any custom MCP/HTTP client — from any machine — with the WhatsApp connection surviving client restarts, multiple clients sharing one socket, and a push telling you on your phone when you need to re-scan a QR.
Related MCP server: whatsapp-mcp
Features
HTTP MCP endpoint (
httpStreamtransport) — connect from anywhere, share the session across multiple clients without Baileys fighting for the socketBearer-token auth on the MCP endpoint, one token per number
Several numbers on one host — each number is its own container, pairing, database and MCP endpoint (
/<label>/mcp); every server tells the agent which line it is, so a message does not leave from the wrong numberHub page behind a PIN — one card per number with its connection state and the QR code to pair it; tap the ntfy push and scan from your phone browser
ntfy push on: first QR after disconnect, every 2min while still waiting, connection drop, reconnect after drop, and unexpected pairings
Bad-pairing protection — if the wrong phone scans a QR code, the app auto-logs out and purges credentials (
EXPECTED_WA_NUMBER)23 MCP tools — search contacts/messages, list chats, send text/media, react, delete, mark read, download media, plus reactive monitoring (cursor delta, long-poll, a
follow_chatWebSocket stream) and webhook subscriptions for real-time inbound push (see table below)Persistent SQLite (chats/messages/contacts) and Baileys multi-file auth stored in a Docker volume
Architecture
flowchart LR
subgraph clients[MCP clients]
CC[Claude Code / Desktop / Cursor / custom agents]
end
PB[Phone browser]
CC -- "https + Bearer" --> T[Traefik]
PB -- "https + PIN" --> T
T -- "/" --> HUB[Hub page]
T -- "/<label>/mcp :39001" --> MCP[FastMCP httpStream]
subgraph container[whatsapp-mcp-<label> container, one per number]
MCP
ST[":39002 status + QR"]
BA[Baileys]
end
HUB -. "reads, inside Docker" .-> ST
MCP --> BA
ST --> BA
BA -- "WA Web API" --> WA[(WhatsApp servers)]
container -- "outbound POST" --> NT[ntfy.sh] -- push --> PH[Your phone]One hostname. Traefik terminates TLS (Let's Encrypt) and routes by path: each number's container answers under /<label>/, and a small hub container answers everything else behind a PIN. A number's status port is never routed publicly — the hub reads it inside the Docker network.
Quick start for MCP clients
A deployment exposes one hostname of your choosing (wa.example.com below — substitute your own). With a number labelled personal:
https://wa.example.com/personal/mcp— MCP endpoint of that number, requiresAuthorization: Bearer <that number's MCP_AUTH_TOKEN>https://wa.example.com/— the hub page (PIN): connection state and QR code of every number, and a ready client entry for each
Add one client entry per number, named after it — the name is what the agent sees when it picks a tool.
Claude Code
Edit ~/.claude.json, in the top-level mcpServers object:
"whatsapp-personal": {
"type": "http",
"url": "https://wa.example.com/personal/mcp",
"headers": {
"Authorization": "Bearer ${WHATSAPP_PERSONAL_TOKEN}"
}
}Export WHATSAPP_PERSONAL_TOKEN in your shell (or put the token literally — ~/.claude.json is 0600). Restart Claude Code, run /mcp — should show whatsapp-personal: ✓ Connected. A second number is a second entry (whatsapp-work → /work/mcp) with its own token.
Claude Desktop
~/.config/Claude/claude_desktop_config.json (Linux) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"whatsapp-personal": {
"type": "http",
"url": "https://wa.example.com/personal/mcp",
"headers": { "Authorization": "Bearer your-token-here" }
}
}
}Cursor
~/.cursor/mcp.json — same shape as Claude Desktop above.
Other clients / custom code
See examples/ for a raw HTTPS JSON-RPC transcript (curl), a Python client, and a custom TypeScript agent using StreamableHTTPClientTransport.
MCP tools
The server exposes 23 tools. Full reference: docs/tools.md.
Category | Tools |
Connection / Auth |
|
Contacts |
|
Messages |
|
Reactive monitoring |
|
Chats |
|
Groups |
|
Sending |
|
Actions |
|
Media |
|
Webhooks |
|
Deployment
Full deploy / add a number / update / rotate-secrets / troubleshoot runbook: deploy/README.md. Two compose files: deploy/docker-compose.yaml runs the shared stack (the hub; env template deploy/.env.example), and deploy/docker-compose.instance.yaml runs one WhatsApp number and its own media store, once per number, each with its own env file — token, expected number, send policy and store credentials (template: deploy/instance.env.example).
This repo depends on its sibling baileys-client (link:../baileys-client), so clone both side by side. Build recipe (BuildKit):
git clone https://github.com/eusoubrasileiro/baileys-client.git
git clone https://github.com/eusoubrasileiro/whatsapp-mcp.git
cd whatsapp-mcp
DOCKER_BUILDKIT=1 docker build \
--build-context baileys=../baileys-client \
-t whatsapp-mcp:latest .Local development
For development without Docker, keep the default stdio transport. Build the sibling baileys-client checkout first (see Deployment):
(cd ../baileys-client && pnpm install && pnpm build)
pnpm install
pnpm test # vitest — git hooks enforce it on every commit
pnpm typecheck
pnpm start # node --experimental-strip-types src/main.tsRequires Node.js 24 (.nvmrc; engines asks for >= 24) for --experimental-strip-types and native better-sqlite3.
For local HTTP mode (same as production minus Traefik):
MCP_TRANSPORT=httpstream MCP_AUTH_TOKEN=dev pnpm start
# then: curl -H 'Authorization: Bearer dev' http://127.0.0.1:39001/mcp ...See scripts/smoke-test.sh for the auth matrix, and docs/development.md for tests, hooks and conventions.
Environment variables
Full table: docs/configuration.md. Highlights:
Variable | Purpose |
| Bearer token required by the HTTP MCP endpoint (mandatory in production; one per number) |
| Name this WhatsApp line. The server then tells agents which line it is, in its instructions, in |
| Unset = no push notifications; set to enable |
| Number allowed to pair; wrong scan → auto-logout + purge (set it for every number, in the form WhatsApp itself uses for it) |
| Opens the hub page (hub only; the other |
| Base dir for |
| Powers |
| Transcription route: |
| OpenRouter model for image description (default |
Data storage & privacy
Credentials:
WHATSAPP_MCP_DATA_DIR/auth_info/(Baileys multi-file auth state)Messages / chats / contacts:
WHATSAPP_MCP_DATA_DIR/data/whatsapp.db(SQLite via Drizzle +better-sqlite3)Media: each number has its own RustFS container, with its own credentials, served behind Traefik at
https://wa.example.com/<label>/media/<key>; a link works only under the label of the number that produced it. Thedownload_mediatool returns an MCPresource_linkpointing at that URL (publicly fetchable, no Bearer needed) plus inlineimageContent/audioContenton the first call. Cache hits return the URL only.Audio → text: by default,
download_mediaon an audio/ptt message transcribes via OpenRouter Whisper (openai/whisper-large-v3) after preprocessing to 16 kHz mono FLAC. The response is wrapped in an<transcription>XML block. Passtranscribe: falseto get raw audio bytes instead. RequiresOPENROUTER_API_KEY. Groq and OpenAI remain as rollback routes viaAUDIO_PROVIDER(each needs its own key).Image → text: opt-in via
download_media({ ..., describe: true }). Sends the image to an OpenRouter vision model (VISION_MODEL, defaultopenai/gpt-6-luna); response wrapped in an<image_description>XML block. RequiresOPENROUTER_API_KEY.Logs:
WHATSAPP_MCP_DATA_DIR/{wa,mcp}-logs.txt(pino JSON lines)
Everything stays on the VPS (Docker bind mount in production, filesystem in dev). Data leaves the VPS only when an MCP client explicitly invokes a tool.
All data directories are .gitignored. Treat them as sensitive — anyone with auth_info/ can impersonate your WhatsApp session.
Credits
Conceptual origin: lharries/whatsapp-mcp (Go + Python).
Fork history: started from
jlucaso1/whatsapp-mcp-ts, since heavily rewritten (HTTP transport, send guards, media plane, reactive monitoring).Maintained by eusoubrasileiro.
License
MIT — see LICENSE, which also carries the ISC notice for the portions derived from jlucaso1/whatsapp-mcp-ts.
Not affiliated with WhatsApp or Meta. Baileys is an unofficial WhatsApp Web client; automating a WhatsApp account can get it restricted — read docs/account-restrictions.md before sending from a number you care about.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
WhatsMCP connects Claude and other MCP-compatible AI agents directly to WhatsApp. Send and receive text, images, documents, and voice notes; manage groups (create, add/remove members, promote admins); look up contacts and profiles; follow channels; and read call and message history — all through a standard MCP interface. For voice use cases, WhatsMCP offers SIP-based calling plans (inbound-only, or full inbound/outbound) so AI voice agents can answer and place WhatsApp calls, plus low-latency WebSocket integrations with voice agent providers like ElevenLabs. Multiple WhatsApp accounts can be paired and managed per workspace, with webhook support for real-time inbound message delivery to your own infrastructure.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
WhatsApp MCP on your own number: read chats, search contacts, send messages.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to interact with WhatsApp via MCP tools for searching contacts, sending/receiving messages, and managing chats, running in a Docker container with HTTP/SSE transport.MIT
- AlicenseNot gradedqualityDmaintenanceEnables sending WhatsApp messages from MCP clients using a personal WhatsApp account via WebSocket protocol, without needing the Business API or browser automation.49 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP server that turns WhatsApp into agent-callable tools, enabling search contacts, send/receive messages, read chats, handle media, and monitor calls via the WhatsApp Web multi-device protocol.11 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables connecting a personal WhatsApp number to any MCP client, providing tools to send, search, and manage WhatsApp messages, with an optional auto-reply feature.5MIT