内容
<p align="center">
<img src="https://raw.githubusercontent.com/ardennguyen/zalo-mcp/main/assets/mascot.png" width="120" alt="zalo-mcp mascot" />
</p>
# 工具列表
独立 **模型上下文协议（MCP）** 服务器安装包，用于 Zalo。 一键式沙盒部署环境，帮助 AI 代理（Claude Code，Cursor）自动执行 Zalo 个人和官方账户，而不会污染您的主机系统。
**[简体中文](#快速开始)** | **[English](#english)**
> [!TIP]
> **`zalo-mcp` 和 `zalo-agent-cli` 之间的区别？**
> - **`zalo-agent-cli`**：核心自动化引擎。负责所有繁重的 API 逻辑、身份验证，并包含实际的 MCP 服务器源代码。
> - **`zalo-mcp`（此仓库）**：轻量级部署包装器。不包含核心代码。相反，其一键式脚本安全地将引擎拉入本地沙盒文件夹，设置 Node/Python，并配置 `.env`，以便 Claude/Cursor 可以立即运行，同时保持您的全局系统干净。
---
## 📋 系统要求
在运行安装程序之前，请确保您的计算机上已安装：
* **Node.js**：版本 22 或更高（MCP 服务器必需）。
* **Python**：版本 3.8 或更高（可选，用于渲染图表和 PDF）。
* **Git**：拉取依赖项所需。
---
## 🚀 快速开始（一键安装）
**macOS / Linux：**
```bash
curl -fsSL https://raw.githubusercontent.com/ardennguyen/zalo-mcp/main/zalo-mcp.sh | bash -s install
```
**Windows (PowerShell)：**
```powershell
Set-ExecutionPolicy Bypass -Scope Process -Force; irm https://raw.githubusercontent.com/ardennguyen/zalo-mcp/main/zalo-mcp.ps1 | Out-File $env:TEMP\zalo-mcp.ps1; & $env:TEMP\zalo-mcp.ps1 install
```
### 安装程序将执行以下操作：
1. 在当前位置创建 `zalo-mcp` 目录。
2. 下载包装器文件和配置文件。
3. 在本地 `node_modules/` 目录中安装 Node.js 包。
4. 创建独立的 Python 虚拟环境（`venv/`）。
5. 创建配置文件 `.env`。
*(注意：您可能会被要求输入端口号，如果您以交互模式运行，或者您可以在以后自行编辑 `.env`。)*
---
## 🔑 登录和身份验证
所有身份验证信息都安全地存储在您的本地计算机上。
### A. 个人 Zalo 账户（非官方 API）
1. 运行登录命令：
```bash
npm run login
```
2. 使用手机上的 Zalo 应用程序扫描打印的二维码。
> [!IMPORTANT]
> **安全通知：** 此使用非官方 API。 如果您的个人账户因大量垃圾邮件而被滥用，可能会被封禁。
### B. Zalo 官方账户（官方 API v3.0）
1. 初始化 OA 凭证：
```bash
npm run oa:init -- --app-id <YOUR_APP_ID> --secret <YOUR_APP_SECRET>
```
2. 按照浏览器提示进行操作。
随时刷新令牌：`npm run oa:refresh`
---
## 🤖 AI 代理集成（MCP）
配置您的 AI 客户端以运行服务器的 stdio 模式：
**Claude Code（`~/.claude/settings.json`）：**
```json
{
"mcpServers": {
"zalo": {
"command": "node",
"args": ["/绝对路径/to/zalo-mcp/mcp-server.js"],
"cwd": "/绝对路径/to/zalo-mcp"
}
}
}
```
**Cursor：** 添加新的 MCP 服务器：`stdio` -> `node /绝对路径/to/zalo-mcp/mcp-server.js`
---
## 🛠️ 管理命令
* **更新依赖项：** `.\zalo-mcp.ps1 update` 或 `./zalo-mcp.sh update`
* **清理环境：** `.\zalo-mcp.ps1 clean` 或 `./zalo-mcp.sh clean`
---
## 📖 文档
**[完整 Wiki → github.com/ardennguyen/zalo-agent-cli/wiki](https://github.com/ardennguyen/zalo-agent-cli/wiki)**
所有命令、MCP 设置、本地缓存、官方账户 API 等的详细指南 - 同时提供英文和简体中文版本。
---
## License
[MIT](LICENSE)
