MCP 服务器

wechat-gateway-mcp

MCP server that lets AI agents manage WeChat Work customer relations via a self-hosted gateway, supporting contact/tag/content queries, group messaging previews and creation, and moment SOP rules with confirm-before-send safety.

README

企业微信网关 · MCP Server

一个开源的 MCP（Model Context Protocol） Server，让 AI Agent（如 WorkBuddy）通过自然语言指令驱动你自己部署的「企业微信客户管理网关」：

查客户 / 标签 / 内容库
预览并创建企业群发任务
预览并创建朋友圈 SOP 规则
查询任务状态、取消任务

⚠️ 本仓库只是 MCP 客户端。它不包含企业微信后端网关本身——你需要先自行部署一套「企微网关」后端（见下方「后端网关部署（概览）」），再用本仓库连上去。所有真实发送动作默认只做预览，需显式 confirm=true 才真正调用网关接口，避免误操作群发。

架构

┌──────────────┐   stdio + MCP    ┌──────────────────┐   HTTPS (Bearer)   ┌──────────────────────┐
│  AI Agent     │ ───────────────▶ │  wechat-gateway   │ ─────────────────▶ │  企业微信网关后端       │
│ (WorkBuddy)  │                  │  MCP Server       │                    │  (FastAPI 等，自部署)  │
└──────────────┘                  └──────────────────┘                    └──────────────────────┘
                                        ↑
                                   WG_BASE_URL / WG_API_TOKEN
                                   （你的 .env，不提交）

MCP Server（本仓库）：读取 WG_BASE_URL / WG_API_TOKEN，把 Agent 的意图转成网关 API 调用。
网关后端（自部署）：对接企业微信「客户联系」API，负责真实的客户同步、群发、朋友圈等，用 MCP_API_TOKEN 校验本 Server 的身份。

功能与工具清单

只读 / 发现类

工具	说明
`list_accounts`	列出网关已配置的企业微信账号（corpid 列表）
`list_members(corpid)`	列出账号下的成员（userID），作群发/朋友圈 sender 候选
`list_tags(corpid)`	列出客户标签（tag_id + 名称）
`search_contacts(corpid, keyword, tag_id, userid, page, size)`	搜索客户（external_userid + 名称 + 标签）
`list_contents(corpid, kind, tag, scene, kw, page, size)`	浏览内容库（图文/视频/链接）
`get_content(cid)`	获取单条内容详情
`list_group_send_tasks(corpid, page, size, status)`	列出历史群发任务
`get_task_status(task_id, corpid)`	查询群发任务执行状态与回执
`list_moment_rules(corpid)`	列出朋友圈 SOP 规则

动作类（默认只预览、需 confirm=true 才真发）

工具	说明
`preview_group_send(...)`	群发预览：校验参数 + 估算接收人数，不发送
`create_group_send(confirm, ...)`	创建企业群发；`confirm=false` 仅预览
`create_moment_rule(confirm, ...)`	创建朋友圈 SOP；`confirm=false` 仅预览
`cancel_group_send(task_id, account)`	停止待发送群发任务
`cancel_moment_task(task_id)`	停止未完成的朋友圈任务
`get_moment_task_result(task_id)`	查询朋友圈任务最终发布情况
`resolve_content(cid, target)`	把内容库条目解析成可直接发送的结构（自动取 media_id）

前置条件

已部署一套企业微信网关后端，并获得：
- 后端 admin API 地址（形如 https://gateway.your-domain.com/api/v1/admin）
- 后端分配的服务令牌 MCP_API_TOKEN
本地 Python 3.10+
一个支持 MCP 的 Agent 客户端（如 WorkBuddy）

快速开始

# 1) 克隆
git clone https://github.com/stevebi88/wecom-gateway-mcp.git
cd wecom-gateway-mcp

# 2) 配置环境变量（复制模板，填入你自己的网关地址与令牌）
cp .env.example .env
#   编辑 .env：
#     WG_BASE_URL=https://gateway.your-domain.com/api/v1/admin
#     WG_API_TOKEN=你网关后端分配的令牌

# 3) 安装并注册到 WorkBuddy（自动建 venv + 装依赖 + 写 mcp.json）
python3 install.py

完成后，在 WorkBuddy 左侧「连接器」找到 wechat-gateway，点 Trust 启用即可。启用后直接对 AI 说：

「给所有 VIP 标签客户群发这条春分活动文案」

Agent 会自行：找标签 → 估算人数 → 预览 →（你确认后）创建群发任务。

配置项

变量	必填	默认	说明
`WG_BASE_URL`	是	`https://your-wechat-gateway.example.com/api/v1/admin`	网关 admin API 基址（结尾不含斜杠）
`WG_API_TOKEN`	是	空	网关后端 `MCP_API_TOKEN`，用于 Bearer 鉴权

手动接入（不使用安装器）

在 WorkBuddy「连接器管理」手动添加一个 stdio 型 MCP：

{
  "mcpServers": {
    "wechat-gateway": {
      "command": "/绝对路径/wechat-gateway-mcp/.venv/bin/python",
      "args": ["/绝对路径/wechat-gateway-mcp/server.py"],
      "env": {
        "WG_BASE_URL": "https://gateway.your-domain.com/api/v1/admin",
        "WG_API_TOKEN": "你网关后端分配的令牌"
      },
      "disabled": false
    }
  }
}

或直接用 run.sh 启动（它会读取同目录 .env）。

安全护栏

所有真实发送（create_group_send / create_moment_rule）默认 confirm=false，只做预览、不发送。
仅当 Agent 显式 confirm=true 才真实调用网关接口。
网关后端用 MCP_API_TOKEN 服务令牌鉴权；本 Server 与令牌仅在你自有的网关与本地之间使用。
.env 含令牌，已被 .gitignore 忽略，请妥善保管、切勿提交或泄露。

后端网关部署（概览）

后端代码不在本仓库。以下为部署该 MCP 所连网关的参考架构，便于你自行搭建或核对环境。

建议栈（示例）：FastAPI（ASGI） + gunicorn + Nginx + Redis + SQLAlchemy，Python 3.12。

后端需提供的关键能力 / 配置：

企业微信「客户联系」相关凭据（corpid / secret / agentid 等），由后端自行保管，不要放进本 MCP 仓库。
暴露 admin API（本 Server 调用的各路径：/accounts、/tags、/contacts、/contents、/group_send/*、/moment/*、/media/{id}/media_id 等）。
后端 .env 需要有一个 MCP_API_TOKEN，其值与本 Server 的 WG_API_TOKEN 一致，用于校验调用方身份。
媒体素材建议转存对象存储（如 COS），避免 resolve_content 取 media_id 时因素材过期失败。