企业微信网关 · 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 的身份。

Related MCP server: wx4py-mcp

功能与工具清单

只读 / 发现类

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

前置条件

1. 已部署一套企业微信网关后端，并获得：

   • 后端 admin API 地址（形如 https://gateway.your-domain.com/api/v1/admin）

   • 后端分配的服务令牌 MCP_API_TOKEN

2. 本地 Python 3.10+

3. 一个支持 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 会自行：找标签 → 估算人数 → 预览 →（你确认后）创建群发任务。

配置项

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

在 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 时因素材过期失败。

部署后拿到 admin 基址与 MCP_API_TOKEN，回填到本仓库 .env 即可。

已知数据问题

历史迁移素材若未转存对象存储，图片/视频类发送时 resolve_content 取 media_id 可能报「素材过期」。纯文本 / 链接发送不受影响；图片类发送需后端重新上传素材或转存对象存储。

许可证

MIT