WeChat Work Gateway · MCP Server

An open-source MCP (Model Context Protocol) Server that lets AI Agents (such as WorkBuddy) drive your self-deployed "WeChat Work Customer Management Gateway" through natural language instructions:

• Query customers / tags / content library

• Preview and create enterprise group send tasks

• Preview and create Moments SOP rules

• Query task status, cancel tasks

⚠️ This repository is only the MCP client. It does not include the WeChat Work backend gateway itself — you need to first deploy a "WeChat Work Gateway" backend on your own (see "Backend Gateway Deployment (Overview)" below), then connect this repository to it. All real send actions default to preview only; the gateway API is only actually called when confirm=true is explicitly set, to avoid accidental group sends.

Architecture

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

• MCP Server (this repository): Reads WG_BASE_URL / WG_API_TOKEN, converts the Agent's intent into gateway API calls.

• Gateway backend (self-deployed): Integrates with the WeChat Work "Customer Contact" API, handles real customer sync, group sends, Moments, etc., and uses MCP_API_TOKEN to authenticate this Server's identity.

Related MCP server: wx4py-mcp

Features and Tool List

Read-only / discovery

Action (preview only by default, requires confirm=true to actually send)

Prerequisites

1. A WeChat Work gateway backend deployed, with:

   • The backend admin API address (e.g. https://gateway.your-domain.com/api/v1/admin)

   • The service token MCP_API_TOKEN assigned by the backend

2. Local Python 3.10+

3. An MCP-capable Agent client (such as WorkBuddy)

Quick Start

# 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

After completion, find wechat-gateway under "Connectors" on the left side of WorkBuddy, and click Trust to enable it. Once enabled, just tell the AI:

"Send this Spring Equinox campaign copy to all VIP-tagged customers via group send"

The Agent will automatically: find the tag → estimate the recipient count → preview → (after you confirm) create the group send task.

Configuration

Manual Integration (without using the installer)

Manually add a stdio-type MCP in WorkBuddy's "Connector Management":

{
  "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
    }
  }
}

Or start it directly with run.sh (it reads the .env file in the same directory).

Security Guardrails

• All real sends (create_group_send / create_moment_rule) default to confirm=false, preview only, no sending.

• The gateway API is only actually called when the Agent explicitly sets confirm=true.

• The gateway backend authenticates using the MCP_API_TOKEN service token; this Server and the token are only used between your own gateway and your local machine.

• .env contains the token and is ignored by .gitignore; keep it safe, never commit or leak it.

Backend Gateway Deployment (Overview)

The backend code is not in this repository. The following is a reference architecture for deploying the gateway that this MCP connects to, to help you build it yourself or verify your environment.

Suggested stack (example): FastAPI (ASGI) + gunicorn + Nginx + Redis + SQLAlchemy, Python 3.12.

Key capabilities / configuration the backend needs to provide:

• WeChat Work "Customer Contact" credentials (corpid / secret / agentid, etc.), kept by the backend itself, do not put them in this MCP repository.

• Expose the admin API (the paths this Server calls: /accounts, /tags, /contacts, /contents, /group_send/*, /moment/*, /media/{id}/media_id, etc.).

• The backend .env needs an MCP_API_TOKEN whose value matches this Server's WG_API_TOKEN, used to verify the caller's identity.

• Media assets are recommended to be migrated to object storage (such as COS), to avoid resolve_content failing to fetch media_id due to expired assets.

After deployment, get the admin base URL and MCP_API_TOKEN, and fill them back into this repository's .env.

Known Data Issues

For historically migrated assets that have not been transferred to object storage, resolve_content may report "asset expired" when fetching media_id for image/video sends. Plain text / link sends are unaffected; image sends require the backend to re-upload the asset or migrate it to object storage.

License

MIT