WeChat-Unternehmensgateway · MCP Server

Ein Open-Source-MCP (Model Context Protocol) Server, der es KI-Agenten (wie WorkBuddy) ermöglicht, dein selbst bereitgestelltes „Enterprise-WeChat-Kundenmanagement-Gateway" über natürliche Sprachbefehle zu steuern:

• Kunden / Tags / Inhaltsbibliothek abfragen

• Massenversand-Aufgaben (Enterprise) in der Vorschau anzeigen und erstellen

• Momente-SOP-Regeln in der Vorschau anzeigen und erstellen

• Aufgabenstatus abfragen, Aufgaben abbrechen

⚠️ Dieses Repository ist nur der MCP-Client. Es enthält nicht das Enterprise-WeChat-Backend-Gateway selbst – du musst zuerst selbst ein „WeCom-Gateway"-Backend bereitstellen (siehe unten „Backend-Gateway-Bereitstellung (Überblick)"), und dieses Repository dann damit verbinden. Alle tatsächlichen Sendeaktionen sind standardmäßig nur Vorschauen; erst mit explizitem confirm=true wird die Gateway-Schnittstelle tatsächlich aufgerufen, um versehentliche Massensendungen zu vermeiden.

Architektur

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

• MCP Server (dieses Repository): Liest WG_BASE_URL / WG_API_TOKEN und übersetzt die Absichten des Agenten in Gateway-API-Aufrufe.

• Gateway-Backend (selbst bereitgestellt): Bindet an die WeCom-„Kundenkontakt"-Schnittstelle an und ist für die tatsächliche Kundensynchronisierung, Massenversand, Momente usw. verantwortlich. Es validiert die Identität dieses Servers über MCP_API_TOKEN.

Related MCP server: wx4py-mcp

Funktionen und Tool-Übersicht

Schreibgeschützt / Discovery

Aktionsklasse (standardmäßig nur Vorschau, erfordert confirm=true für echten Versand)

Voraussetzungen

1. Ein WeCom-Gateway-Backend ist bereits bereitgestellt, und du hast Folgendes erhalten:

   • Die admin-API-Adresse des Backends (Format: https://gateway.your-domain.com/api/v1/admin)

   • Das vom Backend zugewiesene Service-Token MCP_API_TOKEN

2. Lokal Python 3.10+

3. Ein MCP-fähiger Agent-Client (wie WorkBuddy)

Schnellstart

# 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

Nach Abschluss findest du links in WorkBuddy unter „Konnektoren" wechat-gateway und klickst auf Trust, um es zu aktivieren. Danach kannst du der KI direkt sagen:

„Sende diese Frühlingstagundnachtgleiche-Kampagnentextnachricht per Massenversand an alle Kunden mit dem VIP-Tag"

Der Agent führt dann selbstständig aus: Tag finden → Empfängerzahl schätzen → Vorschau anzeigen → Massensendeaufgabe erstellen (nach deiner Bestätigung).

Konfigurationsoptionen

Manuelle Einbindung (ohne Installer)

In WorkBuddy unter „Connector-Verwaltung" manuell einen stdio-MCP hinzufügen:

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

Oder direkt mit run.sh starten (dabei wird die .env im selben Verzeichnis gelesen).

Sicherheitsvorkehrungen

• Alle echten Sendungen (create_group_send / create_moment_rule) sind standardmäßig auf confirm=false gesetzt – nur Vorschau, kein Versand.

• Nur wenn der Agent explizit confirm=true setzt, wird die Gateway-Schnittstelle tatsächlich aufgerufen.

• Das Gateway-Backend authentifiziert über MCP_API_TOKEN; dieser Server und das Token werden nur zwischen deinem eigenen Gateway und lokal verwendet.

• Die .env enthält das Token, wurde durch .gitignore ausgeschlossen und muss sicher aufbewahrt werden – niemals committen oder weitergeben.

Backend-Gateway-Bereitstellung (Überblick)

Der Backend-Code befindet sich nicht in diesem Repository. Das Folgende ist eine Referenzarchitektur für das Gateway, mit dem dieser MCP verbunden wird, damit du es selbst aufbauen oder die Umgebung überprüfen kannst.

Empfohlener Stack (Beispiel): FastAPI (ASGI) + gunicorn + Nginx + Redis + SQLAlchemy, Python 3.12.

Das Backend muss die folgenden wichtigen Funktionen / Konfigurationen bereitstellen:

• Anmeldeinformationen für die WeCom-Funktion „Kundenkontakt" (corpid / secret / agentid usw.) werden vom Backend selbst verwaltet und nicht in dieses MCP-Repository eingefügt.

• Die admin-API verfügbar machen (die vom Server aufgerufenen Pfade: /accounts, /tags, /contacts, /contents, /group_send/*, /moment/*, /media/{id}/media_id usw.).

• Die .env des Backends muss ein MCP_API_TOKEN enthalten, dessen Wert mit dem WG_API_TOKEN dieses Servers übereinstimmt, um die Identität zu validieren.

• Medien-Assets sollten idealerweise in einem Objektspeicher (z. B. COS) gespeichert werden, um Fehler bei resolve_content durch abgelaufene Medien zu vermeiden.

Nach der Bereitstellung den admin-API-Endpunkt erhalten und den Wert von MCP_API_TOKEN erhalten, dann in die .env dieses Servers eintragen.

Bekannte Datenprobleme

Bei Bild-/Videoversand kann resolve_content den Fehler „Medien abgelaufen" melden, wenn die Medien-Assets nicht in einen Objektspeicher migriert wurden.

Lizenz

MIT