企業微信ゲートウェイ · MCP Server

オープンソースの MCP（Model Context Protocol） Server。AI Agent（WorkBuddy など）が自然言語の指示で、あなた自身がデプロイした「企業微信顧客管理ゲートウェイ」を操作できるようにします：

• 顧客 / タグ / コンテンツライブラリの照会

• 企業一括送信タスクのプレビューと作成

• モーメンツ SOP ルールのプレビューと作成

• タスク状態の照会、タスクのキャンセル

⚠️ このリポジトリはあくまで MCP クライアントです。企業微信バックエンドゲートウェイ自体は含まれていません。先にご自身で「企微ゲートウェイ」バックエンドをデプロイし（下記「バックエンドゲートウェイのデプロイ（概要）」参照）、その後このリポジトリを接続してください。実際の送信操作はデフォルトでプレビューのみとなり、明示的に confirm=true を指定した場合のみゲートウェイ API を実際に呼び出し、誤操作による一括送信を防止します。

アーキテクチャ

┌──────────────┐   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 を指定した場合のみ、実際にゲートウェイ API を呼び出します。

• ゲートウェイバックエンドは 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 ベース URL と MCP_API_TOKEN を取得し、このリポジトリの .env に書き戻すだけです。

既知のデータ問題

過去の移行素材がオブジェクトストレージに転送保存されていない場合、画像/動画を送信する際に resolve_content で media_id を取得するときに「素材の期限切れ」エラーが発生する可能性があります。プレーン テキスト / リンクの送信は影響を受けません。画像の送信には、バックエンドでの素材の再アップロードまたはオブジェクトストレージへの転送保存が必要です。

ライセンス

MIT