Content
<div align="center">
<br>
<img alt="zaileys-mcp — WhatsApp for AI agents, powered by Zaileys" src="https://github.com/zeative/zaileys-mcp/blob/main/public/icon.png?raw=true" width="130">
<br>
<br>
<h1 align="center">zaileys-mcp — WhatsApp for AI agents, <br /> powered by Zaileys</h1>
<br>
<div align="center">
<a href="https://www.npmjs.com/package/zaileys-mcp"><img src="https://img.shields.io/npm/v/zaileys-mcp.svg" alt="NPM Version"></a>
<a href="https://www.npmjs.com/package/zaileys-mcp"><img src="https://img.shields.io/npm/dw/zaileys-mcp?label=npm&color=%23CB3837" alt="NPM Downloads"></a>
<a href="https://github.com/zeative/zaileys-mcp/releases"><img src="https://img.shields.io/npm/dt/zaileys-mcp" alt="NPM Total Downloads"></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-server-6E56CF" alt="MCP Server"></a>
</div>
<div align="center">
<a href="https://github.com/zeative/zaileys-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
<a href="https://discord.gg/KBHhTTVUc5"><img alt="Discord" src="https://img.shields.io/discord/1105833273415962654?logo=discord&label=discord"></a>
<a href="https://chat.whatsapp.com/GlQfvc83mSH3F6ov06vuCt"><img alt="WhatsApp" src="https://img.shields.io/badge/WhatsApp-Group-25D366?logo=whatsapp&logoColor=white"></a>
<a href="https://github.com/zeative/zaileys-mcp"><img src="https://img.shields.io/github/stars/zeative/zaileys-mcp" alt="GitHub Stars"></a>
<a href="https://github.com/zeative/zaileys-mcp"><img src="https://img.shields.io/github/forks/zeative/zaileys-mcp" alt="GitHub Forks"></a>
</div>
<br>
<div align="center">
<p>
<b>zaileys-mcp</b> is a <a href="https://modelcontextprotocol.io">Model Context Protocol</a> server that gives AI agents — Claude, Cursor, any MCP client — the ability to drive WhatsApp: send messages, media, polls, and locations; read chats and history; manage groups, communities, newsletters, contacts, presence, and profile. Powered by <a href="https://github.com/zeative/zaileys">Zaileys</a>, so QR / pairing-code auth, reconnection, and sessions are handled for you.
</p>
</div>
<div align="center">
[Quick start](#quick-start) •
[Why zaileys-mcp](#why-zaileys-mcp) •
[Install](#install) •
[What you can build](#what-you-can-build) •
[Configuration](#configuration) •
[Docs](https://zeative.github.io/zaileys-mcp/)
</div>
</div>
<br>
> [!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-only` or 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.
```json
{
"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_tools` meta-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-only` mode 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:
```bash
npx -y zaileys-mcp
```
To embed it in your own bot, add it as a dependency:
```bash
npm i zaileys-mcp zaileys # or: pnpm add • yarn add • bun add
```
Requires **Node.js v20+**. Peer dependency: [`zaileys`](https://www.npmjs.com/package/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.
```text
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 })
```
<details>
<summary><b>Full tool catalog</b></summary>
- **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** — `set_profile_name`/`status`/`picture`, `remove_profile_picture`
- **Business** — `business_profile`, `business_catalog`, `business_collections`
</details>
### 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`.
```text
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:
```typescript
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:
```typescript
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:
| Variable | Default | Description |
| --- | --- | --- |
| `ZAILEYS_SESSION` | `mcp` | Session id (auth persists under `./.zaileys/auth/<id>`) |
| `ZAILEYS_AUTH_TYPE` | `qr` | `qr` or `pairing` |
| `ZAILEYS_PHONE` | — | Phone number (E.164 digits) for pairing-code login |
| `ZAILEYS_READONLY` | `false` | `true` exposes only read tools (agent can't send) |
| `ZAILEYS_ALLOWLIST` | — | Comma-separated numbers/JIDs; restricts outbound tools |
| `ZAILEYS_TOOLS` | `progressive` | `progressive` · `full` · `core` · comma-list |
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**](https://zeative.github.io/zaileys-mcp/) — full documentation: getting started, tools, tool strategy, safety
- ⚙️ [**zeative.github.io/zaileys**](https://zeative.github.io/zaileys/) — the WhatsApp engine underneath
- 🔌 [**Model Context Protocol**](https://modelcontextprotocol.io) — the MCP standard
## Issues & feedback
Hit a problem or have a feature request? Open an [issue](https://github.com/zeative/zaileys-mcp/issues).
- [Buy me a coffee ☕](https://saweria.co/zaadevofc) • [Ko-Fi](https://ko-fi.com/zaadevofc) • [Trakteer](https://trakteer.id/zaadevofc)
- ⭐ Star the repo on GitHub
## License
Distributed under the **MIT License**. See [`LICENSE`](https://github.com/zeative/zaileys-mcp/blob/main/LICENSE) for details.
<div align="left">
<p>
<img alt="zaileys-mcp" src="https://github.com/zeative/zaileys-mcp/blob/main/public/icon.png?raw=true" width="28" align="center">
Copyright © 2026 zaadevofc. All rights reserved.
</p>
</div>
