WeCom Bot MCP Server

WeCom Bot MCP 服务

符合模型上下文协议（MCP）的 WeCom（微信企业版）机器人服务实现。

English | 中文

功能

• 支持多种消息类型：
  • Markdown 消息（支持 @提及和字体颜色）
  • Markdown V2 消息（支持表格、列表、嵌入图片）
  • 图片消息（base64／本地文件／URL）
  • 文件消息
  • 模板卡片消息（text_notice 和 news_notice）
• 多机器人支持：配置和使用多个 WeCom 机器人
• 支持 @提及（通过用户 ID 或电话号码）
• 消息历史跟踪
• 可配置的日志系统
• 完整的类型注解
• 基于 Pydantic 的数据验证

要求

• Python 3.10+
• WeCom 机器人 Webhook URL（从 WeCom 群组设置中获取）

安装

有多种方式可以安装 WeCom Bot MCP 服务：

1. 自动安装（推荐）

使用 Smithery（适用于 Claude Desktop）：

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

使用 VSCode 和 Cline 扩展：

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

如果你想在 Python 代码中直接使用此软件包（而不是将其用作 MCP 服务）：

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

持续集成

项目使用 GitHub Actions 进行 CI/CD：

• MR 检查：针对所有拉取请求运行，在 Ubuntu、Windows 和 macOS 上使用 Python 3.10、3.11 和 3.12 进行测试
• 代码覆盖率：将覆盖率报告上传到 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]