WeCom Bot MCP Server

WeCom Bot MCP サーバー

WeCom（WeChat Work）ボット向けの、Model Context Protocol（MCP）準拠サーバー実装です。

English | 中文

特長

• 複数のメッセージタイプに対応：
  • Markdown メッセージ（@メンションとフォントカラー対応）
  • Markdown V2 メッセージ（テーブル、リスト、埋め込み画像対応）
  • 画像メッセージ（base64／ローカルファイル／URL）
  • ファイルメッセージ
  • テンプレートカードメッセージ（text_notice と news_notice）
• 複数ボット対応：複数の WeCom ボットを設定して使用できます
• @メンションに対応（ユーザー ID または電話番号を使用）
• メッセージ履歴の追跡
• 設定可能なログシステム
• 完全な型注釈
• Pydantic ベースのデータ検証

要件

• Python 3.10+
• WeCom Bot Webhook URL（WeCom のグループ設定から取得）

インストール

WeCom Bot MCP サーバーは、いくつかの方法でインストールできます。

1. 自動インストール（推奨）

Smithery を使用する場合（Claude Desktop 向け）：

npx -y @smithery/cli install wecom-bot-mcp-server --client claude

Cline 拡張機能を使って VSCode を使用する場合：

1. VSCode マーケットプレイスから Cline 拡張機能 をインストールします
2. コマンドパレットを開きます（Ctrl+Shift+P / Cmd+Shift+P）
3. 「Cline: Install Package」を検索します
4. 「wecom-bot-mcp-server」と入力し、Enter キーを押します

2. 手動設定

MCP クライアントの設定ファイルにサーバーを追加します。

// For Claude Desktop on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// For Claude Desktop on Windows: %APPDATA%\Claude\claude_desktop_config.json
// For Windsurf: ~/.windsurf/config.json
// For Cline in VSCode: VSCode Settings > Cline > MCP Settings
{
  "mcpServers": {
    "wecom": {
      "command": "uvx",
      "args": [
        "wecom-bot-mcp-server"
      ],
      "env": {
        "WECOM_WEBHOOK_URL": "your-webhook-url"
      }
    }
  }
}

設定

環境変数の設定

単一ボット（デフォルト）

# Windows PowerShell
$env:WECOM_WEBHOOK_URL = "your-webhook-url"

# Optional configurations
$env:MCP_LOG_LEVEL = "DEBUG"  # Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
$env:MCP_LOG_FILE = "path/to/custom/log/file.log"  # Custom log file path

複数ボットの設定

以下のいずれかの方法で複数のボットを設定できます。

方法 1：JSON 設定（推奨）

# Windows PowerShell
$env:WECOM_BOTS = '{"alert": {"name": "Alert Bot", "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx", "description": "For alerts"}, "ci": {"name": "CI Bot", "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=yyy", "description": "For CI/CD"}}'

# Linux/macOS
export WECOM_BOTS='{"alert": {"name": "Alert Bot", "webhook_url": "https://...", "description": "For alerts"}, "ci": {"name": "CI Bot", "webhook_url": "https://...", "description": "For CI/CD"}}'

方法 2：個別の環境変数

# Windows PowerShell
$env:WECOM_BOT_ALERT_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
$env:WECOM_BOT_CI_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=yyy"
$env:WECOM_BOT_NOTIFY_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=zzz"

方法 3：併用モード

# WECOM_WEBHOOK_URL becomes the "default" bot
$env:WECOM_WEBHOOK_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=default"
# Additional bots
$env:WECOM_BOT_ALERT_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=alert"

複数ボットを使用する MCP クライアントの設定

{
  "mcpServers": {
    "wecom": {
      "command": "uvx",
      "args": ["wecom-bot-mcp-server"],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=default",
        "WECOM_BOTS": "{\"alert\": {\"name\": \"Alert Bot\", \"webhook_url\": \"https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=alert\"}, \"ci\": {\"name\": \"CI Bot\", \"webhook_url\": \"https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=ci\"}}"
      }
    }
  }
}

ログ管理

ログシステムでは、クロスプラットフォームでログファイルを管理するために platformdirs.user_log_dir() を使用します。

• Windows：C:\Users\<username>\AppData\Local\hal\wecom-bot-mcp-server\Logs
• Linux：~/.local/state/hal/wecom-bot-mcp-server/log
• macOS：~/Library/Logs/hal/wecom-bot-mcp-server

ログファイル名は mcp_wecom.log で、上記のディレクトリに保存されます。

環境変数を使用して、ログレベルとファイルパスをカスタマイズできます。

• MCP_LOG_LEVEL：DEBUG、INFO、WARNING、ERROR、CRITICAL のいずれかを設定します
• MCP_LOG_FILE：カスタムログファイルのパスを設定します

使用方法

設定が完了すると、MCP クライアントの起動時に MCP サーバーが自動的に実行されます。AI アシスタントで自然言語を使って操作できます。

使用例

シナリオ 1：天気情報を WeCom に送信する

USER: "How's the weather in Shenzhen today? Send it to WeCom"
ASSISTANT: "I'll check Shenzhen's weather and send it to WeCom"
[The assistant will use the send_message tool to send the weather information]

シナリオ 2：会議のリマインダーを送信し、関係者に @メンションする

USER: "Send a reminder for the 3 PM project review meeting, remind Zhang San and Li Si to attend"
ASSISTANT: "I'll send the meeting reminder"
[The assistant will use the send_message tool with mentioned_list parameter]

シナリオ 3：ファイルを送信する

USER: "Send this weekly report to the WeCom group"
ASSISTANT: "I'll send the weekly report"
[The assistant will use the send_file tool]

シナリオ 4：画像を送信する

USER: "Send this chart image to WeCom"
ASSISTANT: "I'll send the image"
[The assistant will use the send_image tool]

利用可能な MCP ツール

サーバーは、AI アシスタントが使用できる以下のツールを提供します。

1. send_message - テキストまたは Markdown メッセージを送信します

   • パラメーター：content、msg_type (markdown/markdown_v2)、mentioned_list、mentioned_mobile_list、bot_id
   • markdown：<@userid> メンションまたはフォントカラーを含むコンテンツに使用します。<@userid> 構文は WeCom の公式メンション形式で、@[email protected] のようなメールアドレスとの競合を避けられます。
   • markdown_v2：テーブル、リスト、埋め込み画像、または一般的なコンテンツに使用します（デフォルト）。

2. send_wecom_file - WeCom にファイルを送信します

   • パラメーター：file_path、bot_id

3. send_wecom_image - WeCom に画像を送信します

   • パラメーター：image_path（ローカルパスまたは URL）、bot_id

4. send_wecom_template_card_text_notice - テキスト通知テンプレートカードを送信します

   • パラメーター：template_card_source、template_card_main_title、template_card_card_action、bot_id、および任意のフィールド
   • 強調コンテンツ、引用、アクションボタンを含む通知に使用します

5. send_wecom_template_card_news_notice - ニュース通知テンプレートカードを送信します

   • パラメーター：template_card_source、template_card_main_title、template_card_card_action、template_card_image、bot_id、および任意のフィールド
   • 画像やリッチコンテンツを含むニュース形式の通知に使用します

6. list_wecom_bots - 設定済みのすべてのボットを一覧表示します

   • 戻り値：利用可能なボットの ID、名前、説明の一覧

複数ボットの使用例

シナリオ 5：特定のボットにアラートを送信

USER: "Send a critical alert to the alert bot: Server CPU usage is above 90%"
ASSISTANT: "I'll send the alert to the alert bot"
[The assistant will use send_message with bot_id="alert"]

シナリオ 6：利用可能なボットを一覧表示

USER: "What WeCom bots are available?"
ASSISTANT: "Let me check the available bots"
[The assistant will use list_wecom_bots tool]

シナリオ 7：CI 通知を送信

USER: "Send build success notification to the CI bot"
ASSISTANT: "I'll send the notification to the CI bot"
[The assistant will use send_message with bot_id="ci"]

シナリオ 8：テンプレートカード通知を送信

USER: "Send a deployment success notification card with a link to the dashboard"
ASSISTANT: "I'll send a template card notification"
[The assistant will use send_wecom_template_card_text_notice tool]

シナリオ 9：ニュース形式の通知を送信

USER: "Send a news card about the new feature release with an image"
ASSISTANT: "I'll send a news notice card"
[The assistant will use send_wecom_template_card_news_notice tool]

開発者向け：API の直接利用

このパッケージを MCP サーバーとしてではなく、Python コードから直接使用する場合：

from wecom_bot_mcp_server import send_message, send_wecom_file, send_wecom_image, send_wecom_template_card

# Send markdown message (uses default bot)
await send_message(content="**Hello World!**", msg_type="markdown")

# Send markdown_v2 message with tables and lists (default)
await send_message(
    content="| Column1 | Column2 |\n|---------|---------|\\n| Value1  | Value2  |", msg_type="markdown_v2"
)

# Send text message and mention users (use markdown for @mentions)
await send_message(content="Hello <@user1> <@user2>", msg_type="markdown", mentioned_list=["user1", "user2"])

# Send message to a specific bot
await send_message(
    content="Build completed successfully!",
    msg_type="markdown_v2",
    bot_id="ci",  # Send to CI bot
)

# Send alert to alert bot
await send_message(content="⚠️ High CPU usage detected!", msg_type="markdown_v2", bot_id="alert")

# Send file to specific bot
await send_wecom_file("/path/to/file.txt", bot_id="ci")

# Send image to specific bot
await send_wecom_image("/path/to/image.png", bot_id="alert")

# Send template card (text_notice)
await send_wecom_template_card(
    template_card_type="text_notice",
    template_card_source={"icon_url": "https://example.com/icon.png", "desc": "System"},
    template_card_main_title={"title": "Deployment Success", "desc": "Production environment"},
    template_card_card_action={"type": 1, "url": "https://example.com/dashboard"},
    template_card_emphasis_content={"title": "100%", "desc": "Success Rate"},
    bot_id="ci",
)

コードでの複数ボットの設定

from wecom_bot_mcp_server.bot_config import get_bot_registry, list_available_bots

# List all available bots
bots = list_available_bots()
for bot in bots:
    print(f"Bot: {bot['id']} - {bot['name']}")

# Check if a specific bot exists
registry = get_bot_registry()
if registry.has_bot("alert"):
    print("Alert bot is configured")

# Get webhook URL for a specific bot
url = registry.get_webhook_url("ci")

開発

開発環境のセットアップ

1. リポジトリをクローンします：

git clone https://github.com/loonghao/wecom-bot-mcp-server.git
cd wecom-bot-mcp-server

2. 仮想環境を作成し、依存関係をインストールします：

# Using uv (recommended)
pip install uv
uv venv
uv pip install -e ".[dev]"

# Or using traditional method
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

テスト

# Run all tests with coverage
uvx nox -s pytest

# Run import tests only
uvx nox -s test_imports

# Run specific test file
uvx nox -s pytest -- tests/test_message.py

# Run tests with verbose output
uvx nox -s pytest -- -v

コードスタイル

# Check code
uvx nox -s lint

# Automatically fix code style issues
uvx nox -s lint_fix

ビルドと公開

# Build the package
uvx nox -s build

# Publish to PyPI (requires authentication)
uvx nox -s publish

継続的インテグレーション

このプロジェクトでは、CI/CD に GitHub Actions を使用しています：

• MR チェック：すべてのプルリクエストで実行され、Python 3.10、3.11、3.12 を使用して Ubuntu、Windows、macOS でテストします
• コードカバレッジ：カバレッジレポートを Codecov にアップロードします
• インポートテスト：インストール後にパッケージを正しくインポートできることを確認します

問題を早期に検出できるよう、CI の実行中にすべての依存関係が自動的にテストされます。

プロジェクト構成

wecom-bot-mcp-server/
├── src/
│   └── wecom_bot_mcp_server/
│       ├── __init__.py
│       ├── __main__.py
│       ├── __version__.py
│       ├── app.py           # FastMCP application setup
│       ├── server.py        # Server entry point
│       ├── message.py       # Message and template card handling
│       ├── file.py          # File upload handling
│       ├── image.py         # Image upload handling
│       ├── bot_config.py    # Multi-bot configuration
│       ├── utils.py         # Utility functions
│       ├── log_config.py    # Logging configuration
│       └── errors.py        # Error definitions
├── tests/
│   ├── test_server.py
│   ├── test_message.py
│   ├── test_file.py
│   ├── test_image.py
│   └── test_bot_config.py
├── docs/
├── pyproject.toml
├── noxfile.py
└── README.md

ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細については、LICENSE ファイルを参照してください。

お問い合わせ

• 作者：longhao
• メール：[email protected]