内容
# socialmate-mcp
<p align="center">
<img src="https://raw.githubusercontent.com/micbwilliam/n8n-nodes-socialmate/main/assets/logo.png" width="96" alt="SocialMate" />
</p>
<p align="center">
<a href="https://www.npmjs.com/package/socialmate-mcp"><img src="https://img.shields.io/npm/v/socialmate-mcp.svg?color=2563eb" alt="npm version" /></a>
<a href="https://www.npmjs.com/package/socialmate-mcp"><img src="https://img.shields.io/npm/dm/socialmate-mcp.svg?color=2563eb" alt="npm downloads" /></a>
<a href="LICENSE"><img src="https://img.shields.io/npm/l/socialmate-mcp.svg" alt="license" /></a>
<img src="https://img.shields.io/node/v/socialmate-mcp.svg" alt="node version" />
</p>
<p align="center"><strong>给你的 AI 一个 WhatsApp。</strong></p>
一个原生的 **[模型上下文协议](https://modelcontextprotocol.io)** 服务器，用于
**[SocialMate](https://socialmate.app)** — 自托管的 WhatsApp 自动化服务器（桌面应用，
或在你的 VPS/Docker 上无头运行，通过浏览器在 `/admin` 中管理）。将
**Claude Desktop, Cursor, Cline** 或任何 MCP 客户端指向它，你的代理可以发送和阅读 WhatsApp
消息，查找联系人，管理群组，排队一批个性化消息，回忆整个对话，**查看人们发送的照片**，
记住它正在与谁交谈以及媒体说什么，并检查防封头部 —
**44 种工具**，所有都在你自己的机器上和你自己的号码上。
> **SocialMate 不包含 AI — 它给 *你的* AI 一个 WhatsApp。** 这个服务器是一个薄
> 翻译层，位于 SocialMate 的本地 REST API 上：每个工具调用都通过应用的真实
> **身份验证 → 范围 → 分级门控 → 防封 → 审计** 管道，因此这里没有任何内容可以绕过限制，
> 应用仍然是单一的真实来源。
- **指南：** https://socialmate.app/docs/mcp-server
- **登录页面：** https://socialmate.app/whatsapp-mcp-server
- **应用：** https://socialmate.app
---
## 要求
- **SocialMate 桌面应用** 正在运行，其本地 API 服务器开启（**API 与集成**）。
- 来自应用的 **API 密钥** （**API 与集成 → 新密钥**）。其范围（读取 / 发送 / 管理）
和你的许可证等级决定了哪些工具有效。
- **Node.js ≥ 18.17** （仅用于运行 `npx`；无需全局安装任何内容）。
## 快速入门 — Claude Desktop
将 SocialMate 添加到你的 `claude_desktop_config.json` （应用在
**API 与集成 → MCP** 下显示了一个复制粘贴代码段）：
```json
{
"mcpServers": {
"socialmate": {
"command": "npx",
"args": ["socialmate-mcp"],
"env": {
"SOCIALMATE_API_KEY": "sm_live_xxx",
"SOCIALMATE_BASE_URL": "http://127.0.0.1:3456"
}
}
}
}
```
重启 Claude Desktop，WhatsApp 工具就会出现。**Cursor, Cline, Goose** 和任何其他 MCP
客户端都使用相同的 `command` / `args` / `env` — 将其放入它们的 MCP 配置中即可。
### 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|---|:---:|---|---|
| `SOCIALMATE_API_KEY` | ✅ | — | 应用的 API 密钥 → API 与集成。 |
| `SOCIALMATE_BASE_URL` | | `http://127.0.0.1:3456` | 应用的 API — 桌面应用或无头 VPS。使用你的 **Pro 命名隧道** 主机驱动 WhatsApp 从远程代理。在 VPS（数据中心 IP）上，你可以通过自己的住宅/移动代理（Pro）路由账户以保持住宅 IP。 |
## 你的代理可以做的事 — 44 种工具
所有名称为 `whatsapp_*`；模型从描述中选择正确的工具。
| 领域 | 工具 |
|---|---|
| **消息传递** | `send_message` （带有 `reply_to` 以引用） · `send_media` · `send_poll` · `get_poll_results` · `send_location` · `send_contact` |
| **对话信号** | `react_message` （`emoji: ""` 删除） · `mark_read` · `send_typing` — 免费在每个等级；它们不消耗发送预算，也不提高风险评分 |
| **内存与读取** | `get_ai_context` （角色映射内存馈送） · `search_messages` · `fetch_new_messages` （轮询游标） · `list_chats` |
| **视觉（查看人们发送的内容）** | `list_media` （`has_context: false` = "我还没看过什么？"） · `get_media` — 返回 **图像块**，所以你的模型可以实际查看它 · `set_media_context` — 保存你看到的内容，这样它就不会被再次分析 |
| **代理内存（写入，Pro）** | `update_contact` （保存你学习的姓名/备注/标签） · `set_media_context` — SocialMate **存储** 你的代理学习的内容，它永远不会生成它 |
| **联系人** | `list_contacts` · `get_contact` |
| **群组** | `list_groups` · `get_group` · `create_group` · `update_group_participants` · `set_group_subject` · `set_group_description` · `get_group_invite` · `leave_group` |
| **队列与批次（Pro）** | `queue_import` — 用于 **已经等待你** 的人：一个 `{{field}}` 模板 + 最多 5000 行，每行成为一个 **单独的、个性化的** 消息，由防封机制控制 · `queue_message` （一个，计划的） · `queue_status` · `list_queue` · `cancel_queued` · `retry_queued` · `list_batches` · `cancel_batch` · `retry_batch` · `pause_queue` · `resume_queue` |
| **同步与状态** | `trigger_sync` · `sync_status` · `get_antiban_status` · `get_capabilities` · `list_accounts` |
账户范围的工具接受一个可选的 `account_id`；使用单个账户密钥时，它是 **自动解析** 的。
一个好的初始调用是 `whatsapp_get_capabilities` — 它告诉代理它的等级、范围和功能
标志，以便它知道在尝试之前它被允许做什么。
**视觉循环。** `list_media` （`has_context: false`）→ `get_media` （项目以真实
图像内容块返回，视觉模型可以查看）→ `set_media_context` （缓存描述）。之后
照片在 `get_ai_context` 中已经描述过，不会再次分析。
`get_media` 返回 **缩略图** — 足以了解照片 **是什么**，大小有限；完整
分辨率字节故意留在 HTTP API 上（见下文）。
**批量发送默认关闭。** `queue_import` 返回 `403 bulk_import_disabled` （线路代码
不变），直到用户在应用中启用它（**设置 → 高级 → "启用批量发送"**）。SocialMate 是
**不是广播工具** — 它用于管理你自己的对话，与
已经等待你的人。每个批次项目都是一个单独的、个性化的消息，由防封引擎控制；相同
文本发送给多个联系人会被重复检查阻止。当
关闭时，服务器告诉代理 **询问**，而不是循环 `send_message` — 这是
导致号码被封的模式。
> **故意不暴露：** API 密钥管理，Webhook 接线，账户代理，媒体
> **写入** （强制下载 / 删除 / 清理），以及 **原始媒体文件** — 代理铸造密钥，
> 重新布线交付，重新路由流量，删除文件，或将 15 MB 块拉入其上下文是一个
> 足枪。在应用中执行这些操作，或通过 HTTP API / n8n。完整的列表，带有每个端点的理由，
> 是 `NOT_EXPOSED` 允许列表，在 [`contract.test.mjs`](contract.test.mjs) 中 — 一个新应用端点
> 失败构建，直到它被赋予一个工具或在那里故意跳过。
## 🧠 一个使代理表现得像人类的种子提示
服务器附带一个 **原生 MCP 提示** — `socialmate_human_agent` — 因此任何支持
`prompts/list` （Claude Desktop, Cursor, …）的客户端都可以将其作为系统提示加载。无需
复制粘贴。
它教授人类回复节奏（*标记已读 → 回忆线程 → 显示输入 → 反应或
回复*），整个工具库存和 **不** 使用每个工具的时机，等级 + 防封错误
合同（`402`，阻止发送，`queueable:false`，`signal_rate_limit`），代理真正
**无法** 做的事情（无编辑/删除/转发；它看不到联系人输入；按钮已
弃用 — 发送投票），以及同意和诚实规则。
用你的业务填充它：
| 参数 | 示例 |
|---|---|
| `business_name` | `Northwind Coffee` |
| `business_description` | `specialty coffee roastery in Cairo` |
| `agent_name` | `Nora` |
| `agent_role` | `front-desk support` |
| `tone` | `warm, concise, never salesy` |
| `business_hours` | `Sun–Thu, 9:00–17:00 Cairo time` |
| `escalation_procedure` | `tagging @ops in Slack and telling the customer a colleague will follow up` |
| `scope_boundaries` | `orders, opening hours and the menu` |
| `additional_rules` | anything extra |
规范文本（和 n8n 版本）：[`docs/AI-AGENT-SYSTEM-PROMPT.md`](../docs/AI-AGENT-SYSTEM-PROMPT.md)。
反应，阅读回执和输入指示器在 **每个等级上都是免费的**，并且不消耗
发送预算 — 代理可以在不花费其消息额度情况下表现得像人类。
## 📥 对传入消息的反应
这是关于 MCP 需要知道的一件事。**MCP 是请求/响应 — 它没有传入推送。**
服务器无法通知 Claude/Cursor WhatsApp 消息刚刚到达；客户端只有在您
要求时才会执行操作。两种方法使代理在消息 **到达时** 做出反应：
1. **轮询（纯 MCP）** — 在循环中调用 `whatsapp_fetch_new_messages` ，将最新的 `timestamp`
作为 `since` 传递，以获取仅更新的内容。需要 Pro（它读取同步的历史记录）。
2. **事件驱动（桥接）** — 从 n8n 的 **SocialMate 触发器** （`message.received`）
或 **Webhook** 启动循环到你自己的代码，然后让代理通过这些工具回过头来。免费
版本也支持（`message.received` Webhook 是一个免费事件）。
对于由手驱动的桌面助手，MCP 单独使用是完美的。对于无人值守的自动回复器，
使用桥接。
### 它是否成功？— 送达回执
`whatsapp_fetch_new_messages` 和 `whatsapp_search_messages` 返回的每个消息行都带有
一个 **`status`**：`pending` → `sent` → `delivered` （它到达了收件人的手机）→ `read` （他们打开了它）。所以
代理可以检查它发送的内容是否实际到达 — 它永远不需要
询问人类。**发送** 返回 `status: "sent"` ，这仅意味着 *交给 WhatsApp*；
这不是到达的证明。
要被 **告知** 消息到达的时刻，请订阅两个回执 Webhook（**Pro**）— 像其他所有
事件一样，它们通过 n8n **SocialMate 触发器** 或你自己的接收器到达，而不是通过 MCP：
| 事件 | 触发条件 |
|---|---|
| `message.delivered` | 你的消息到达了收件人的手机（两个灰色勾选） |
| `message.read` | 他们打开了它（两个蓝色勾选） |
两者都携带 `messageId` ， `status` 和 `fromMe: true` — 在 `messageId` 上关联，
通知循环关闭。它们 **仅为操作员发送的消息** 触发：传入消息
操作员在自己的手机上阅读时不会发出通知，因此 `message.read` 始终意味着 *他们
阅读了你的消息*，而不是 *你阅读了他们的消息*。
## 范围与等级
工具遵循 API 密钥的 **范围** 和你的 **许可证等级**，与 REST API 完全相同：
| | 免费 | 专业版 |
|---|:---:|:---:|
| 读取消息，聊天，联系人，群组 | ✅ | ✅ |
| 发送 **文本** | ✅ | ✅ |
| 防封状态，功能 | ✅ | ✅ |
| 发送 **媒体**，创建/管理群组 | — | ✅ |
| 历史记录，**获取 AI 上下文**，投票游标 | — | ✅ |
| 智能队列（计划/批次/控制） | — | ✅ |
一个受限工具返回一个明确的 *"需要专业版"* 错误，而不是静默失败，以便代理可以
适应（例如，退回到纯文本发送）。
## 开发/探索
使用 MCP 检查器以交互方式浏览和调用每个工具：
```bash
npx @modelcontextprotocol/inspector npx socialmate-mcp
```
运行测试套件（针对模拟 REST API 启动服务器，并通过 MCP 驱动它）：
```bash
npm install
npm test
```
## 更喜欢 n8n？
构建视觉化、触发的工作流，而不是桌面助手？SocialMate 还附带了一个原生的
**[n8n 节点](https://www.npmjs.com/package/n8n-nodes-socialmate)** ，其每个操作都可用作
AI 代理工具。相同的 WhatsApp，不同的客户端 — 查看
[AI 代理指南](https://socialmate.app/docs/n8n-ai-agents)。
## 许可证
[MIT](LICENSE) © SocialMate Ltd.
