企业微信机器人 MCP 服务端

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

smithery徽章

English | 中文

功能特性

支持多种消息类型：
- Markdown消息（支持@提及和字体颜色）
- Markdown V2消息（支持表格、列表、内嵌图片）
- 图片消息（base64/本地文件/URL）
- 文件消息
- 模板卡片消息（文本通知和图文通知）
多机器人支持：可配置并使用多个企业微信机器人
@提及支持（通过用户ID或手机号）
消息历史追踪
可配置的日志系统
完整的类型注解
基于Pydantic的数据验证

系统要求

Python 3.10+
企业微信机器人Webhook地址（从企业微信群设置获取）

安装方式

有多种方式安装企业微信机器人MCP服务端：

1. 自动安装（推荐）

使用Smithery（适用于Claude桌面版）：

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

使用VSCode的Cline扩展：

从VSCode应用市场安装Cline扩展
打开命令面板(Ctrl+Shift+P / Cmd+Shift+P)
搜索"Cline: Install Package"
输入"wecom-bot-mcp-server"并按回车

2. 手动配置

将服务端添加到您的MCP客户端配置文件中：

// macOS上的Claude桌面版: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows上的Claude桌面版: %APPDATA%\Claude\claude_desktop_config.json
// Windsurf: ~/.windsurf/config.json
// VSCode中的Cline: VSCode设置 > Cline > MCP设置
{
  "mcpServers": {
    "wecom": {
      "command": "uvx",
      "args": [
        "wecom-bot-mcp-server"
      ],
      "env": {
        "WECOM_WEBHOOK_URL": "您的webhook地址"
      }
    }
  }
}

配置说明

环境变量设置

单机器人（默认）

# Windows PowerShell
$env:WECOM_WEBHOOK_URL = "您的webhook地址"

# 可选配置
$env:MCP_LOG_LEVEL = "DEBUG"  # 日志级别: DEBUG, INFO, WARNING, ERROR, CRITICAL
$env:MCP_LOG_FILE = "自定义日志文件路径.log"  # 自定义日志文件路径

多机器人配置

可通过以下任一方式配置多个机器人：

方法1：JSON配置（推荐）

# Windows PowerShell
$env:WECOM_BOTS = '{"alert": {"name": "告警机器人", "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx", "description": "用于告警"}, "ci": {"name": "CI机器人", "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=yyy", "description": "用于CI/CD"}}'

# Linux/macOS
export WECOM_BOTS='{"alert": {"name": "告警机器人", "webhook_url": "https://...", "description": "用于告警"}, "ci": {"name": "CI机器人", "webhook_url": "https://...", "description": "用于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作为"default"机器人
$env:WECOM_WEBHOOK_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=default"
# 额外机器人
$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\": \"告警机器人\", \"webhook_url\": \"https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=alert\"}, \"ci\": {\"name\": \"CI机器人\", \"webhook_url\": \"https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=ci\"}}"
      }
    }
  }
}

日志管理

日志系统使用platformdirs.user_log_dir()进行跨平台日志文件管理：

Windows: C:\Users\<用户名>\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：发送天气信息到企业微信

用户："今天深圳天气如何？发送到企业微信"
助手："我将查询深圳天气并发送到企业微信"
[助手将使用send_message工具发送天气信息]

场景2：发送会议提醒并@相关人员

用户："发送下午3点项目评审会议提醒，提醒张三和李四参加"
助手："我将发送会议提醒"
[助手将使用send_message工具并设置mentioned_list参数]

场景3：发送文件

用户："把这份周报发送到企业微信群"
助手："我将发送周报"
[助手将使用send_file工具]

场景4：发送图片

用户："把这张图表图片发送到企业微信"
助手："我将发送图片"
[助手将使用send_image工具]

可用MCP工具

服务端提供以下工具供AI助手使用：

send_message - 发送文本或markdown消息
- 参数: content, msg_type (markdown/markdown_v2), mentioned_list, mentioned_mobile_list, bot_id
- markdown: 当内容包含<@userid>提及或字体颜色时使用。<@userid>语法是企业微信官方提及格式，可避免与@user@email.com等邮箱地址冲突
- markdown_v2: 用于表格、列表、内嵌图片或一般内容（默认）
send_wecom_file - 发送文件到企业微信
- 参数: file_path, bot_id
send_wecom_image - 发送图片到企业微信
- 参数: image_path (本地路径或URL), bot_id
send_wecom_template_card_text_notice - 发送文本通知模板卡片
- 参数: template_card_source, template_card_main_title, template_card_card_action, bot_id等可选字段
- 用于包含重点内容、引用和操作按钮的通知
send_wecom_template_card_news_notice - 发送图文通知模板卡片
- 参数: template_card_source, template_card_main_title, template_card_card_action, template_card_image, bot_id等可选字段
- 用于包含图片和丰富内容的新闻式通知
list_wecom_bots - 列出所有配置的机器人
- 返回: 可用机器人列表，包含ID、名称和描述

多机器人使用示例

场景5：向特定机器人发送告警

用户："向告警机器人发送严重告警：服务器CPU使用率超过90%"
助手："我将向告警机器人发送告警"
[助手将使用send_message并设置bot_id="alert"]

场景6：列出可用机器人

用户："有哪些企业微信机器人可用？"
助手："让我查看可用机器人"
[助手将使用list_wecom_bots工具]

场景7：发送CI通知

用户："向CI机器人发送构建成功通知"
助手："我将向CI机器人发送通知"
[助手将使用send_message并设置bot_id="ci"]

场景8：发送模板卡片通知

用户："发送一个带仪表盘链接的部署成功通知卡片"
助手："我将发送模板卡片通知"
[助手将使用send_wecom_template_card_text_notice工具]

场景9：发送新闻式通知

用户："发送一个关于新功能发布的新闻卡片并附带图片"
助手："我将发送图文通知卡片"
[助手将使用send_wecom_template_card_news_notice工具]

开发者指南：直接API使用

如果您想在Python代码中直接使用此包（不作为MCP服务端）：

from wecom_bot_mcp_server import send_message, send_wecom_file, send_wecom_image, send_wecom_template_card

# 发送markdown消息（使用默认机器人）
await send_message(
    content="**Hello World!**",
    msg_type="markdown"
)

发送支持表格和列表的markdown_v2格式消息（默认）

await send_message( content="| 列1 | 列2 |\n|-----|-----|\n| 值1 | 值2 |", msg_type="markdown_v2" )

发送文本消息并@用户（使用markdown格式@提及）

await send_message( content="你好 <@用户1> <@用户2>", msg_type="markdown", mentioned_list=["用户1", "用户2"] )

向指定机器人发送消息

await send_message( content="构建成功完成！", msg_type="markdown_v2", bot_id="ci" # 发送给CI机器人 )

向告警机器人发送警报

await send_message( content="⚠️ 检测到CPU使用率过高！", msg_type="markdown_v2", bot_id="alert" )

向指定机器人发送文件

await send_wecom_file("/路径/到/文件.txt", bot_id="ci")

向指定机器人发送图片

await send_wecom_image("/路径/到/图片.png", bot_id="alert")

发送模板卡片（文本通知）

await send_wecom_template_card( template_card_type="text_notice", template_card_source={"icon_url": "https://example.com/icon.png", "desc": "系统"}, template_card_main_title={"title": "部署成功", "desc": "生产环境"}, template_card_card_action={"type": 1, "url": "https://example.com/dashboard"}, template_card_emphasis_content={"title": "100%", "desc": "成功率"}, bot_id="ci" )


### 代码中的多机器人配置

```python
from wecom_bot_mcp_server.bot_config import get_bot_registry, list_available_bots

# 列出所有可用机器人
bots = list_available_bots()
for bot in bots:
    print(f"机器人: {bot['id']} - {bot['name']}")

# 检查特定机器人是否存在
registry = get_bot_registry()
if registry.has_bot("alert"):
    print("告警机器人已配置")

# 获取特定机器人的webhook地址
url = registry.get_webhook_url("ci")

开发指南

搭建开发环境

克隆仓库：

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

创建虚拟环境并安装依赖：

# 使用uv（推荐）
pip install uv
uv venv
uv pip install -e ".[dev]"

# 或使用传统方法
python -m venv venv
source venv/bin/activate  # Windows系统: venv\Scripts\activate
pip install -e ".[dev]"

测试

# 运行所有测试并生成覆盖率报告
uvx nox -s pytest

# 仅运行导入测试
uvx nox -s test_imports

# 运行特定测试文件
uvx nox -s pytest -- tests/test_message.py

# 显示详细输出运行测试
uvx nox -s pytest -- -v

代码风格

# 代码检查
uvx nox -s lint

# 自动修复代码风格问题
uvx nox -s lint_fix

构建与发布

# 构建包
uvx nox -s build

# 发布到PyPI（需要认证）
uvx nox -s publish

持续集成

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

合并请求检查：在所有PR上运行，测试Ubuntu、Windows和macOS系统下的Python 3.10、3.11和3.12版本
代码覆盖率：将覆盖率报告上传至Codecov
导入测试：确保安装后能正确导入包

所有依赖项在CI过程中都会自动测试以尽早发现问题。

项目结构

企业微信机器人MCP服务/
├── 源代码/
│   └── wecom_bot_mcp_server/
│       ├── __init__.py
│       ├── __main__.py
│       ├── __version__.py
│       ├── app.py           # FastMCP应用配置
│       ├── server.py        # 服务入口点
│       ├── message.py       # 消息和模板卡处理
│       ├── file.py          # 文件上传处理
│       ├── image.py         # 图片上传处理
│       ├── bot_config.py    # 多机器人配置
│       ├── utils.py         # 工具函数
│       ├── log_config.py    # 日志配置
│       └── errors.py        # 错误定义
├── 测试/
│   ├── test_server.py
│   ├── test_message.py
│   ├── test_file.py
│   ├── test_image.py
│   └── test_bot_config.py
├── 文档/
├── pyproject.toml
├── noxfile.py
└── 自述文件.md

许可证

本项目采用MIT许可证 - 详见LICENSE文件。

联系方式

作者：longhao
邮箱：hal.long@outlook.com