WeCom Bot MCP服务器
WeCom（WeChat Work）机器人的模型上下文协议（MCP）兼容服务器实现。
特性
- 支持多种消息类型：
- 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将VSCode与Cline扩展一起使用：
- 安装 临床扩展 来自VSCode市场
- 打开命令面板（Ctrl+Shift+P/Cmd+Shift+P）
- 搜索“临床：安装包”
- 键入“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() 对于跨平台日志文件管理：
- 窗户：
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：设置为调试、信息、警告、错误或严重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助手可以使用的以下工具：
- send_message -发送文本或标记消息
- 参数： content, msg_type （markdown/markdown_v2）， mentioned_list, mentioned_mobile_list, bot_id - markdown：当内容包含以下内容时使用 ` 提及或字体颜色。这 语法是微信的官方提及格式，它避免了与电子邮件地址的冲突，如 @user@email.com - markdown_v2`：用于表格、列表、嵌入图像或常规内容（默认）
- send_wecom_文件 -将文件发送到WeCom
- 参数： file_path, bot_id
- send_wecom_image -将图片发送至WeCom
- 参数： image_path （本地路径或URL）， bot_id
- send_wecom_template_card_text_note通知 -发送短信通知模板卡
- 参数： 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：向特定机器人发送警报
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 ",
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": "", "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")发展
设置开发环境
- 克隆存储库：
git clone https://github.com/loonghao/wecom-bot-mcp-server.git
cd wecom-bot-mcp-server- 创建虚拟环境并安装依赖项：
# 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 for 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许可证获得许可-请参阅 许可证 文件以获取详细信息。
联系
- 作者：龙浩
- 电子邮件：hal.long@outlook.com
