内容
<div align="center">
<br>
<img alt="zaileys-mcp — WhatsApp AI 代理， 由 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 AI 代理， <br /> 由 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 版本"></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 下载量"></a>
<a href="https://github.com/zeative/zaileys-mcp/releases"><img src="https://img.shields.io/npm/dt/zaileys-mcp" alt="NPM 总下载量"></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-server-6E56CF" alt="MCP 服务器"></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="许可证：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 星数"></a>
<a href="https://github.com/zeative/zaileys-mcp"><img src="https://img.shields.io/github/forks/zeative/zaileys-mcp" alt="GitHub 分叉数"></a>
</div>
<br>
<div align="center">
<p>
<b>zaileys-mcp</b> 是一个 <a href="https://modelcontextprotocol.io">模型上下文协议</a> 服务器，允许 AI 代理（如 Claude、Cursor 或任何 MCP 客户端）控制 WhatsApp：发送消息、媒体、投票和位置；读取聊天记录和管理群组、社区、通讯稿、联系人、在线状态和个人资料。由 <a href="https://github.com/zeative/zaileys">Zaileys</a> 提供支持，因此二维码/配对码身份验证、重新连接和会话由 Zaileys 处理。
</p>
</div>
<div align="center">
[快速开始](#快速开始) •
[为什么选择 zaileys-mcp](#为什么选择zaileys-mcp) •
[安装](#安装) •
[您可以构建的内容](#您可以构建的内容) •
[配置](#配置) •
[文档](https://zeative.github.io/zaileys-mcp/)
</div>
</div>
<br>
> [!NOTE]
> 本 README 是一个**高级别概述**。完整的指南、工具目录和配置参考资料位于 **<https://zeative.github.io/zaileys-mcp/>**。
> [!WARNING]
> 该项目通过非官方 Web API（通过 Zaileys/Baileys）驱动一个**真实的 WhatsApp 账户**。WhatsApp 可能会暂停使用非官方自动化工具的号码，而 AI 代理使用这些工具可以向您账户中的任何人发送消息。在不需要完全访问时，请使用 `read-only` 或允许列表，并且永远不要将其指向您无法承受损失的账户。
---
## 快速开始
将其添加到您的 MCP 客户端 — `npx` 按需获取它。首次启动时打印一个二维码以在 **WhatsApp → 已连接设备** 中扫描；会话持续存在。
```json
{
"mcpServers": {
"whatsapp": {
"command": "npx",
"args": ["-y", "zaileys-mcp"],
"env": { "ZAILEYS_SESSION": "my-wa" }
}
}
}
```
就是这样。重启您的客户端，然后询问您的代理：
> "向 +62 812 3456 7890 发送 WhatsApp 消息，部署完成 ✅"
> "总结我在家庭群组中的最后 20 条消息。"
与 **Claude Desktop**、**Cursor** 和任何支持 stdio 的 MCP 客户端兼容。
## 为什么选择 zaileys-mcp
- **与 Zaileys 完全 1:1** — 60+ 个涵盖消息、聊天、群组、社区、通讯稿、隐私、个人资料、在线状态、联系人和商业功能的工具。Zaileys 可以做的任何事情，代理都可以做。
- **智能工具策略** — 所有 60+ 个工具都存在，但只有一小部分**核心**工具保留在代理的上下文中；其余工具通过 `find_tools` 元工具按需公开。完全功能，上下文小，不会使每个请求膨胀。
- **零配置身份验证** — Zaileys 处理 WhatsApp 连接。首次运行时打印二维码；会话持续存在，重启时连接静默。
- **可嵌入** — 已经运行 Zaileys 机器人？在一行代码中将其公开给 AI 代理，它重用您的实时会话，无需第二次登录。
- **安全设计** — `read-only` 模式和收件人允许列表适用于代理不应具有完全访问权限的情况。
- **干净的传输** — stdio JSON-RPC 保持无损坏；二维码和日志输出到 stderr。支持自定义 HTTP/SSE 传输。
## 安装
无需安装独立服务器 — `npx` 处理它：
```bash
npx -y zaileys-mcp
```
要将其嵌入到您自己的机器人中，请将其作为依赖项添加：
```bash
npm i zaileys-mcp zaileys # 或：pnpm add • yarn add • bun add
```
需要 **Node.js v20+**。对等依赖：[`zaileys`](https://www.npmjs.com/package/zaileys) `>= 4.7`。
## 您可以构建的内容
### 从您的代理驱动 WhatsApp
**60+ 个工具，与 Zaileys API 完全 1:1** — 每个 `to` / `chat` / `jid` 都接受电话号码或 JID。
```text
代理： "将 +62 811 111 111 添加到周末群组并使其成为管理员"
→ find_tools("添加群组成员") → 启用 group_add, group_promote, …
→ group_add({ group, participants })
→ group_promote({ group, participants })
```
<details>
<summary><b>完整的工具目录</b></summary>
- **消息** — `send_text`, `send_media`, `send_location`, `send_poll`, `send_contact`, `send_sticker`, `react`, `edit_message`, `delete_message`, `forward_message`, `pin_message`, `unpin_message`
- **聊天** — `list_chats`, `get_messages`, `chat_archive`/`unarchive`/`pin`/`unpin`/`mute`/`unmute`/`mark_read`/`mark_unread`/`delete`/`clear`, `set_disappearing`
- **账户和联系人** — `me`, `check_number`, `get_profile`, `save_contact`, `remove_contact`
- **在线状态** — `send_typing`, `send_recording`, `set_presence`
- **群组** — `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`
- **社区** — `community_metadata`/`list`/`subgroups`/`create`/`link_group`/`unlink_group`/`leave`
- **通讯稿** — `newsletter_metadata`/`messages`/`create`/`follow`/`unfollow`/`mute`/`unmute`/`react`
- **隐私** — `privacy_get`, `blocklist`, `block`, `unblock`
- **个人资料** — `set_profile_name`/`status`/`picture`, `remove_profile_picture`
- **商业** — `business_profile`, `business_catalog`, `business_collections`
</details>
### 智能工具策略
60+ 个工具对于每个请求来说太多了。zaileys-mcp 使用 **渐进式工具公开**（默认）：只有一小部分 **核心** 工具保持活跃，其余工具通过 `find_tools` 元工具按需公开。
```text
ZAILEYS_TOOLS=progressive # ~13 个核心工具活跃，其余通过 find_tools （默认）
ZAILEYS_TOOLS=full # 所有 60+ 个工具活跃
ZAILEYS_TOOLS=core # ~12 个核心工具，无发现
ZAILEYS_TOOLS=send_text,get_messages # 精选的一组工具 + find_tools
```
### 嵌入到您自己的机器人中
已经运行 Zaileys 客户端？在一行代码中将其公开给 AI 代理 — 它重用您的实时会话：
```typescript
import { Client } from 'zaileys'
import { serveMcp } from 'zaileys-mcp'
const client = new Client()
await serveMcp(client) // AI 代理现在可以通过 stdio 控制此 WhatsApp
```
只读、允许列表或自定义传输：
```typescript
import { createMcpServer, serveMcp } from 'zaileys-mcp'
await serveMcp(client, { readOnly: true, allowlist: ['62812xxxxxxx'] })
const server = createMcpServer(client) // 使用您自己的 HTTP/SSE 传输
await server.connect(myHttpTransport)
```
## 配置
独立（环境变量）— 程序选项一一对应：
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `ZAILEYS_SESSION` | `mcp` | 会话 ID（身份验证在 `./.zaileys/auth/<id>` 下持续存在） |
| `ZAILEYS_AUTH_TYPE` | `qr` | `qr` 或 `pairing` |
| `ZAILEYS_PHONE` | — | 配对码登录的电话号码（E.164 数字） |
| `ZAILEYS_READONLY` | `false` | `true` 仅公开读取工具（代理无法发送） |
| `ZAILEYS_ALLOWLIST` | — | 以逗号分隔的号码/JIDs；限制输出工具 |
| `ZAILEYS_TOOLS` | `progressive` | `progressive` · `full` · `core` · 以逗号分隔的列表 |
两个防护措施，可在任何模式下使用： **`readOnly`** （写入工具从未注册）和 **`allowlist`** （输出工具拒绝其他收件人）。推荐：用于总结器/监视器的 `readOnly`，用于个人/团队通知的 `allowlist`，用于完全自动化的专用号码。
## 文档
- 🌐 [**zeative.github.io/zaileys-mcp**](https://zeative.github.io/zaileys-mcp/) — 完整的文档：入门指南、工具、工具策略、安全
- ⚙️ [**zeative.github.io/zaileys**](https://zeative.github.io/zaileys/) — WhatsApp 引擎
- 🔌 [**模型上下文协议**](https://modelcontextprotocol.io) — MCP 标准
## 问题和反馈
遇到问题或有功能请求？打开一个 [问题](https://github.com/zeative/zaileys-mcp/issues)。
- [给我买杯咖啡 ☕](https://saweria.co/zaadevofc) • [Ko-Fi](https://ko-fi.com/zaadevofc) • [Trakteer](https://trakteer.id/zaadevofc)
- ⭐ 在 GitHub 上为该仓库点赞
## 许可证
在 **MIT 许可证**下分发。有关详细信息，请参见 [`LICENSE`](https://github.com/zeative/zaileys-mcp/blob/main/LICENSE)。
<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. 版权所有。
</p>
</div>
