Quick start • Why zaileys-mcp • Install • What you can build • Configuration • Docs
[!NOTE] This README is a high-level overview. The complete guides, tool catalog, and configuration reference live in the documentation site at https://zeative.github.io/zaileys-mcp/.
[!WARNING] This drives a real WhatsApp account through the unofficial Web API (via Zaileys/Baileys). WhatsApp may suspend numbers that use unofficial automation, and an AI agent with these tools can message anyone in your account. Use
read-onlyor an allowlist when you don't need full access, and never point it at an account you can't afford to lose.
Quick start
Add it to your MCP client — npx fetches it on demand. First launch prints a QR to scan in WhatsApp → Linked Devices; the session persists.
{
"mcpServers": {
"whatsapp": {
"command": "npx",
"args": ["-y", "zaileys-mcp"],
"env": { "ZAILEYS_SESSION": "my-wa" }
}
}
}
That's it. Restart your client, then ask your agent:
"Send a WhatsApp to +62 812 3456 7890 that the deploy is done ✅"
"Summarize my last 20 messages in the family group."
Works with Claude Desktop, Cursor, and any MCP client that speaks stdio.
Why zaileys-mcp
- Full 1:1 with Zaileys — 60+ tools covering messaging, chats, groups, communities, newsletters, privacy, profile, presence, contacts, and business. Anything Zaileys can do, an agent can do.
- Smart tool strategy — all 60+ tools exist, but only a small core stays in the agent's context; the rest are revealed on demand via a
find_toolsmeta-tool. Full capability, small context — no bloating every request. - Zero-config auth — Zaileys handles the WhatsApp connection. First run prints a QR; the session persists, restarts connect silently.
- Embeddable — already run a Zaileys bot? Expose it to AI agents in one line; it reuses your live session, no second login.
- Safe by design —
read-onlymode and recipient allowlists for when an agent shouldn't have full reach. - Clean transport — stdio JSON-RPC stays uncorrupted; QR and logs go to stderr. Custom HTTP/SSE transport supported.
Install
No install needed for the standalone server — npx handles it:
npx -y zaileys-mcp
To embed it in your own bot, add it as a dependency:
npm i zaileys-mcp zaileys # or: pnpm add • yarn add • bun add
Requires Node.js v20+. Peer dependency: zaileys >= 4.7.
What you can build
Drive WhatsApp from your agent
60+ tools, 1:1 with the Zaileys API — every to / chat / jid accepts a phone number or a JID interchangeably.
Agent: "add +62 811 111 111 to the Weekend group and make them admin"
→ find_tools("add member to group") → enables group_add, group_promote, …
→ group_add({ group, participants })
→ group_promote({ group, participants })
- Messaging —
send_text,send_media,send_location,send_poll,send_contact,send_sticker,react,edit_message,delete_message,forward_message,pin_message,unpin_message - Chats —
list_chats,get_messages,chat_archive/unarchive/pin/unpin/mute/unmute/mark_read/mark_unread/delete/clear,set_disappearing - Account & contacts —
me,check_number,get_profile,save_contact,remove_contact - Presence —
send_typing,send_recording,set_presence - Groups —
group_metadata/list/create/add/remove/promote/demote/update_subject/update_description/leave/invite_code/invite_revoke/invite_info/invite_accept/join_requests/approve_join/reject_join/setting/join_approval/member_add_mode/toggle_ephemeral - Communities —
community_metadata/list/subgroups/create/link_group/unlink_group/leave - Newsletters —
newsletter_metadata/messages/create/follow/unfollow/mute/unmute/react - Privacy —
privacy_get,blocklist,block,unblock - Profile — //,
Smart tool strategy
60+ tools is a lot to inject into an agent's context on every request. zaileys-mcp uses progressive tool disclosure (the default): only a small core (~13 tools) stays active, and the rest are revealed on demand via a find_tools meta-tool that enables matches and fires MCP's tools/list_changed.
ZAILEYS_TOOLS=progressive # ~13 core active, rest via find_tools (default)
ZAILEYS_TOOLS=full # all 60+ active
ZAILEYS_TOOLS=core # ~12 core, no discovery
ZAILEYS_TOOLS=send_text,get_messages # a hand-picked set (+ find_tools)
Embed in your own bot
Already run a Zaileys client? Expose it to AI agents in one line — it reuses your live session:
import { Client } from 'zaileys'
import { serveMcp } from 'zaileys-mcp'
const client = new Client()
await serveMcp(client) // AI agents can now drive this WhatsApp over stdio
Read-only, allowlist, or a custom transport:
import { createMcpServer, serveMcp } from 'zaileys-mcp'
await serveMcp(client, { readOnly: true, allowlist: ['62812xxxxxxx'] })
const server = createMcpServer(client) // bring your own HTTP/SSE transport
await server.connect(myHttpTransport)
Configuration
Standalone (env vars) — programmatic options mirror these one-to-one:
Two guardrails, usable in any mode: readOnly (write tools never registered) and allowlist (outbound tools refuse other recipients). Recommended: readOnly for summarizers/monitors, allowlist for personal/team notifiers, a dedicated number for full automation.
Documentation
- 🌐 zeative.github.io/zaileys-mcp — full documentation: getting started, tools, tool strategy, safety
- ⚙️ zeative.github.io/zaileys — the WhatsApp engine underneath
- 🔌 Model Context Protocol — the MCP standard
Issues & feedback
Hit a problem or have a feature request? Open an issue.
- Buy me a coffee ☕ • Ko-Fi • Trakteer
- ⭐ Star the repo on GitHub
License
Distributed under the MIT License. See LICENSE for details.
