Gateway de WeChat Work · MCP Server

Un servidor MCP (Model Context Protocol) de código abierto que permite a los agentes de IA (como WorkBuddy) impulsar mediante instrucciones en lenguaje natural el gateway de gestión de clientes de WeChat Work que tú mismo implementas:

• Consultar clientes / etiquetas / biblioteca de contenido

• Previsualizar y crear tareas de envío masivo empresarial

• Previsualizar y crear reglas de SOP de Moments

• Consultar el estado de las tareas y cancelarlas

⚠️ Este repositorio es solo un cliente MCP. No incluye el gateway backend de WeChat Work en sí: primero debes implementar tu propio backend de «gateway de WeChat Work» (consulta «Implementación del gateway backend (resumen)» más abajo) y luego conectar este repositorio a él. Todas las acciones de envío reales solo hacen una previsualización por defecto; solo una llamada explícita con confirm=true invoca de verdad la interfaz del gateway, para evitar envíos masivos accidentales.

Arquitectura

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

• Servidor MCP (este repositorio): lee WG_BASE_URL / WG_API_TOKEN y convierte la intención del agente en llamadas a la API del gateway.

• Backend del gateway (autoimplementado): se conecta a la API de «Contacto con clientes» de WeChat Work; se encarga de la sincronización real de clientes, de los envíos masivos, de los Moments, etc., y utiliza MCP_API_TOKEN para verificar la identidad de este servidor.

Related MCP server: wx4py-mcp

Lista de funciones y herramientas

Solo lectura / descubrimiento

Acciones (solo previsualización por defecto; requieren confirm=true para enviar de verdad)

Requisitos previos

1. Tener implementado un backend de gateway de WeChat Work y disponer de:

   • La dirección de la API admin del backend (por ejemplo, https://gateway.your-domain.com/api/v1/admin)

   • El token de servicio MCP_API_TOKEN asignado por el backend

2. Python 3.10+ local

3. Un cliente de agente compatible con MCP (por ejemplo, WorkBuddy)

Inicio rápido

# 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

Cuando termines, en «Conectores» a la izquierda de WorkBuddy, busca wechat-gateway y haz clic en Trust para activarlo. Después de activarlo, dile directamente a la IA:

«Envía este texto de la actividad del equinoccio de primavera a todos los clientes con la etiqueta VIP»

El agente hará lo siguiente por sí mismo: encontrar la etiqueta → estimar el número de personas → previsualizar → (después de que lo confirmes) crear la tarea de envío masivo.

Opciones de configuración

Conexión manual (sin usar el instalador)

En «Administración de conectores» de WorkBuddy, añade manualmente un MCP de tipo stdio:

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

O inícialo directamente con run.sh (leerá el .env del mismo directorio).

Medidas de seguridad

• Todos los envíos reales (create_group_send / create_moment_rule) tienen confirm=false por defecto: solo previsualizan, no envían.

• Solo cuando el agente especifica explícitamente confirm=true se invoca de verdad la interfaz del gateway.

• El backend del gateway se autentica mediante el token de servicio MCP_API_TOKEN; este servidor y el token solo se usan entre tu propio gateway y tu máquina local.

• El .env contiene el token y ya está ignorado por .gitignore; consérvalo de forma segura y nunca lo envíes ni lo expongas.

Implementación del gateway backend (resumen)

El código del backend no está en este repositorio. A continuación se muestra la arquitectura de referencia para implementar el gateway al que se conecta este MCP, de modo que puedas montarlo tú mismo o verificar tu entorno.

Pila recomendada (ejemplo): FastAPI (ASGI) + gunicorn + Nginx + Redis + SQLAlchemy, Python 3.12.

El backend debe ofrecer las siguientes capacidades / configuración clave:

• Las credenciales relacionadas con «Contacto con clientes» de WeChat Work (corpid / secret / agentid, etc.) deben ser custodiadas por el backend; no las incluyas en este repositorio MCP.

• Exponer la API admin (las rutas que este servidor invoca: /accounts, /tags, /contacts, /contents, /group_send/*, /moment/*, /media/{id}/media_id, etc.).

• El .env del backend debe incluir un MCP_API_TOKEN cuyo valor coincida con el WG_API_TOKEN de este servidor, para verificar la identidad de quien realiza la llamada.

• Se recomienda transferir los archivos multimedia a un almacenamiento de objetos (por ejemplo, COS) para evitar que resolve_content falle al obtener media_id por caducidad del material.

Después de la implementación, obtén la dirección base de admin y el MCP_API_TOKEN, y rellénalos en el .env de este repositorio.

Problemas de datos conocidos

Si los archivos migrados históricamente no se han transferido a un almacenamiento de objetos, al enviar imágenes/vídeos resolve_content puede notificar «material caducado» al obtener media_id. El envío de texto plano / enlaces no se ve afectado; para el envío de imágenes, el backend debe volver a subir el material o transferirlo a un almacenamiento de objetos.

Licencia

MIT