Шлюз WeChat Work · MCP Server

Открытый MCP (Model Context Protocol) сервер, который позволяет AI-агенту (например, WorkBuddy) управлять вашим развёрнутым «шлюзом клиентского менеджмента WeChat Work» с помощью команд на естественном языке:

• Поиск клиентов / тегов / библиотеки контента

• Предпросмотр и создание задач корпоративной рассылки

• Предпросмотр и создание правил SOP для моментов (朋友圈)

• Запрос статуса задач, отмена задач

⚠️ Этот репозиторий — только MCP-клиент. Он не содержит сам бэкенд-шлюз WeChat Work — вам нужно сначала самостоятельно развернуть бэкенд «шлюза WeChat Work» (см. «Развёртывание бэкенд-шлюза (обзор)» ниже), а затем подключить к нему этот репозиторий. Все реальные действия по отправке по умолчанию выполняют только предпросмотр; для фактического вызова API шлюза требуется явный confirm=true, чтобы избежать случайных массовых рассылок.

Архитектура

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

• MCP-сервер (этот репозиторий): читает WG_BASE_URL / WG_API_TOKEN, преобразует намерения агента в вызовы API шлюза.

• Бэкенд-шлюз (самостоятельное развёртывание): взаимодействует с API «контактов с клиентами» WeChat Work, отвечает за реальную синхронизацию клиентов, массовые рассылки, моменты и т. д., проверяет личность этого сервера с помощью MCP_API_TOKEN.

Related MCP server: wx4py-mcp

Функции и список инструментов

Только чтение / обнаружение

Действия (по умолчанию только предпросмотр, реальная отправка только при confirm=true)

Предварительные требования

1. Развёрнут бэкенд-шлюза WeChat Work, и получены:

   • Адрес admin API бэкенда (например, https://gateway.your-domain.com/api/v1/admin)

   • Сервисный токен MCP_API_TOKEN, выданный бэкендом

2. Локально Python 3.10+

3. MCP-совместимый клиент агента (например, 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

После завершения найдите wechat-gateway в разделе «Коннекторы» слева в WorkBuddy и нажмите Trust для включения. После включения просто скажите ИИ:

«Отправь всем клиентам с тегом VIP эту рассылку с текстом о весеннем равноденствии»

Агент сам: найдёт тег → оценит количество → предпросмотр → (после вашего подтверждения) создаст задачу массовой рассылки.

Параметры конфигурации

Ручное подключение (без использования установщика)

В «Управлении коннекторами» WorkBuddy вручную добавьте MCP типа 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
    }
  }
}

Или запустите напрямую через run.sh (он читает .env из той же директории).

Защитные барьеры

• Все реальные отправки (create_group_send / create_moment_rule) по умолчанию confirm=false — только предпросмотр, без отправки.

• Только когда агент явно указывает confirm=true, происходит реальный вызов API шлюза.

• Бэкенд-шлюз аутентифицируется сервисным токеном MCP_API_TOKEN; этот сервер и токен используются только между вашим собственным шлюзом и локальной машиной.

• .env содержит токен, он игнорируется .gitignore; храните его надёжно, никогда не коммитьте и не раскрывайте.

Развёртывание бэкенд-шлюза (обзор)

Код бэкенда не в этом репозитории. Ниже — референсная архитектура для развёртывания шлюза, к которому подключается этот MCP, чтобы вы могли самостоятельно его построить или проверить окружение.

Рекомендуемый стек (пример): FastAPI (ASGI) + gunicorn + Nginx + Redis + SQLAlchemy, Python 3.12.

Ключевые возможности / конфигурация, которые должен предоставлять бэкенд:

• Учётные данные «контактов с клиентами» WeChat Work (corpid / secret / agentid и т. д.), хранятся самим бэкендом, не кладите их в этот MCP-репозиторий.

• Предоставление admin API (пути, которые вызывает этот сервер: /accounts, /tags, /contacts, /contents, /group_send/*, /moment/*, /media/{id}/media_id и т. д.).

• В .env бэкенда должен быть MCP_API_TOKEN, значение которого совпадает с WG_API_TOKEN этого сервера, для проверки личности вызывающего.

• Медиа-материалы рекомендуется переносить в объектное хранилище (например, COS), чтобы resolve_content не выдавал ошибку при получении media_id из-за истечения срока действия материала.

После развёртывания получите базовый адрес admin и MCP_API_TOKEN и заполните их в .env этого репозитория.

Известные проблемы с данными

Если исторические мигрированные материалы не перенесены в объектное хранилище, при отправке изображений/видео resolve_content при получении media_id может выдавать ошибку «материал истёк». Отправка чистого текста / ссылок не затрагивается; для отправки изображений бэкенду нужно заново загрузить материал или перенести его в объектное хранилище.

Лицензия

MIT# Шлюз WeChat Work · MCP Server

Открытый MCP (Model Context Protocol) сервер, который позволяет AI-агенту (например, WorkBuddy) управлять вашим развёрнутым «шлюзом управления клиентами WeChat Work» с помощью команд на естественном языке:

• Поиск клиентов / тегов / библиотеки контента

• Предпросмотр и создание задач корпоративной рассылки

• Предпросмотр и создание правил SOP для моментов

• Запрос статуса задач, отмена задач

⚠️ Этот репозиторий — только MCP-клиент. Он не содержит сам бэкенд-шлюз WeChat Work — вам нужно сначала самостоятельно развернуть бэкенд «шлюза WeChat Work» (см. «Развёртывание бэкенд-шлюза (обзор)» ниже), а затем подключить к нему этот репозиторий. Все реальные отправки по умолчанию выполняют только предпросмотр; для реального вызова API шлюза требуется явный confirm=true, чтобы избежать случайных массовых рассылок.

Архитектура

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

• MCP-сервер (этот репозиторий): читает WG_BASE_URL / WG_API_TOKEN, преобразует намерения агента в вызовы API шлюза.

• Бэкенд-шлюз (самостоятельное развёртывание): взаимодействует с API «контактов с клиентами» WeChat Work, отвечает за реальную синхронизацию клиентов, массовые рассылки, моменты и т. д., проверяет личность этого сервера через MCP_API_TOKEN.

Функции и список инструментов

Только чтение / обнаружение

Действия (по умолчанию только предпросмотр, реальная отправка только при confirm=true)

Предпосылки

1. Развёрнут бэкенд-шлюз WeChat Work, и получены:

   • Адрес admin API бэкенда (в виде https://gateway.your-domain.com/api/v1/admin)

   • Сервисный токен MCP_API_TOKEN, выданный бэкендом

2. Локально Python 3.10+

3. MCP-совместимый клиент агента (например, 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

После завершения найдите wechat-gateway в разделе «Коннекторы» слева в WorkBuddy и нажмите Trust, чтобы включить. После включения можно сразу сказать ИИ:

«Отправь всем клиентам с тегом VIP эту массовую рассылку с текстом о весеннем равноденствии»

Агент сам: найдёт тег → оценит количество → предпросмотр → (после вашего подтверждения) создаст задачу массовой рассылки.

Параметры конфигурации

Ручное подключение (без использования установщика)

В «Управлении коннекторами» WorkBuddy вручную добавьте MCP- 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
    }
  }
}

Или запустите напрямую через run.sh (он читает .env из той же директории).

Защитные барьеры

• Все реальные отправки (create_group_send / create_moment_rule) по умолчанию имеют confirm=false — только предпросмотр, без отправки.

• Только когда агент явно указывает confirm=true, происходит реальный вызов API шлюза.

• Бэкенд-шлюз аутентифицируется сервисным токеном MCP_API_TOKEN; этот сервер и токен используются только между вашим собственным шлюзом и локальной машиной.

• .env содержит токен, он игнорируется .gitignore; храните его надёжно, никогда не коммитьте и не раскрывайте.

Развёртывание бэкенд-шлюза (обзор)

Код бэкенда не в этом репозитории. Ниже — референсная архитектура для развёртывания шлюза, к которому подключается этот MCP, чтобы вы могли самостоятельно его построить или проверить окружение.

Рекомендуемый стек (пример): FastAPI (ASGI) + gunicorn + Nginx + Redis + SQLAlchemy, Python 3.12.

Ключевые возможности / конфигурации, которые должен предоставлять бэкенд:

• Учётные данные «контактов с клиентами» WeChat Work (corpid / secret / agentid и т. д.), хранятся самим бэкендом, не кладите их в этот MCP-репозиторий.

• Предоставление admin API (пути, которые вызывает этот сервер: /accounts, /tags, /contacts, /contents, /group_send/*, /moment/*, /media/{id}/media_id и т. д.).

• В .env бэкенда должен быть MCP_API_TOKEN, значение которого совпадает с WG_API_TOKEN этого сервера, для проверки личности вызывающего.

• Медиа-материалы рекомендуется переносить в объектное хранилище (например, COS), чтобы resolve_content не выдавал ошибку при получении media_id из-за истечения срока действия материала.

После развёртывания получите базовый адрес admin и MCP_API_TOKEN и заполните их в .env этого репозитория.

Известные проблемы с данными

Если исторические мигрированные материалы не перенесены в объектное хранилище, при отправке изображений/видео resolve_content при получении media_id может выдавать ошибку «материал истёк». Отправка чистого текста / ссылок не затрагивается; для отправки изображений бэкенду нужно повторно загрузить материал или перенести его в объектное хранилище.

Лицензия

MIT