WeCom

WeCom Bot MCP Server

A Model Context Protocol (MCP) compliant server implementation for WeCom (WeChat Work) bot.

English | 中文

Features

• Support for multiple message types:
  • Markdown messages (with @mentions and font colors)
  • Markdown V2 messages (with tables, lists, embedded images)
  • Image messages (base64/local file/URL)
  • File messages
  • Template card messages (text_notice and news_notice)
• Multi-bot support: Configure and use multiple WeCom bots
• @mention support (via user ID or phone number)
• Message history tracking
• Configurable logging system
• Full type annotations
• Pydantic-based data validation

Requirements

• Python 3.10+
• WeCom Bot Webhook URL (obtained from WeCom group settings)

Installation

There are several ways to install WeCom Bot MCP Server:

1. Automated Installation (Recommended)

Using Smithery (For Claude Desktop):

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

Using VSCode with Cline Extension:

1. Install Cline Extension from VSCode marketplace
2. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
3. Search for "Cline: Install Package"
4. Type "wecom-bot-mcp-server" and press Enter

2. Manual Configuration

Add the server to your MCP client configuration file:

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

Configuration

Setting Environment Variables

Single Bot (Default)

# 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

Multiple Bots Configuration

You can configure multiple bots using any of these methods:

Method 1: JSON Configuration (Recommended)

# 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"}}'

Method 2: Individual Environment Variables

# 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"

Method 3: Combined Mode

# 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 Client Configuration with Multiple Bots

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

Log Management

The logging system uses platformdirs.user_log_dir() for cross-platform log file management:

• 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

The log file is named mcp_wecom.log and is stored in the above directory.

You can customize the log level and file path using environment variables:

• MCP_LOG_LEVEL: Set to DEBUG, INFO, WARNING, ERROR, or CRITICAL
• MCP_LOG_FILE: Set to a custom log file path

Usage

Once configured, the MCP server runs automatically when your MCP client starts. You can interact with it through natural language in your AI assistant.

Usage Examples

Scenario 1: Send weather information to 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]

Scenario 2: Send meeting reminder and @mention relevant people

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]

Scenario 3: Send a file

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

Scenario 4: Send an image

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

Available MCP Tools

The server provides the following tools that your AI assistant can use:

1. send_message - Send text or markdown messages

   • Parameters: content, msg_type (markdown/markdown_v2), mentioned_list, mentioned_mobile_list, bot_id
   • markdown: Use when content contains <@userid> mentions or font colors. The <@userid> syntax is WeCom's official mention format, which avoids conflicts with email addresses like @user@email.com
   • markdown_v2: Use for tables, lists, embedded images, or general content (default)

2. send_wecom_file - Send files to WeCom

   • Parameters: file_path, bot_id

3. send_wecom_image - Send images to WeCom

   • Parameters: image_path (local path or URL), bot_id

4. send_wecom_template_card_text_notice - Send text notice template card

   • Parameters: template_card_source, template_card_main_title, template_card_card_action, bot_id, and optional fields
   • Use for notifications with emphasis content, quotes, and action buttons

5. send_wecom_template_card_news_notice - Send news notice template card

   • Parameters: template_card_source, template_card_main_title, template_card_card_action, template_card_image, bot_id, and optional fields
   • Use for news-style notifications with images and rich content

6. list_wecom_bots - List all configured bots

   • Returns: List of available bots with their IDs, names, and descriptions

Multi-Bot Usage Examples

Scenario 5: Send alert to specific bot

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"]

Scenario 6: List available bots

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

Scenario 7: Send CI notification

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"]

Scenario 8: Send template card notification

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]

Scenario 9: Send news-style notification

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]

For Developers: Direct API Usage

If you want to use this package directly in your Python code (not as an MCP server):

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_m

---

*README truncated. [View full README on GitHub](https://github.com/loonghao/wecom-bot-mcp-server).*