企业微信机器人MCP服务器

Name: 企业微信机器人MCP服务器
Author: loonghao

作者：loonghao64 星标更新：2025-11-21

安装使用来源：spider==github.com

项目介绍

WeCom Bot MCP Server

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

English | 中文

功能

支持多种消息类型：
- 文本消息
- Markdown 消息
- 图片消息（base64）
- 文件消息
@提及支持（通过用户ID或电话号码）
消息历史跟踪
可配置的日志系统
完整的类型注解
基于 Pydantic 的数据验证

要求

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

安装

有几种方式可以安装 WeCom Bot MCP Server：

1. 自动安装（推荐）

使用 Smithery（适用于 Claude Desktop）：

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

使用 VSCode 和 Cline 扩展：

从 VSCode 市场安装 Cline 扩展
打开命令面板（Ctrl+Shift+P / Cmd+Shift+P）
搜索“Cline: 安装包”
输入“wecom-bot-mcp-server”并按 Enter

2. 手动配置

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

// 对于 macOS 上的 Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
// 对于 Windows 上的 Claude Desktop: %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": "your-webhook-url"
      }
    }
  }
}

配置

设置环境变量

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

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

日志管理

日志系统使用 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: 向 WeCom 发送天气信息

用户: "深圳今天的天气怎么样？发送到 WeCom"
助手: "我将检查深圳的天气并发送到 WeCom"
[助手将使用 send_message 工具发送天气信息]

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

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

场景 3: 发送文件

用户: "将这份周报发送到 WeCom 群组"
助手: "我将发送周报"
[助手将使用 send_file 工具]

场景 4: 发送图片

用户: "将这张图表图片发送到 WeCom"
助手: "我将发送图片"
[助手将使用 send_image 工具]

可用的 MCP 工具

服务器提供了以下工具供您的AI助手使用：

send_message - 发送文本或Markdown消息
- 参数：content, msg_type (text/markdown), mentioned_list, mentioned_mobile_list
send_file - 向 WeCom 发送文件
- 参数：file_path
send_image - 向 WeCom 发送图片
- 参数：image_path (本地路径或URL)

开发者直接使用API

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

from wecom_bot_mcp_server import send_message, send_wecom_file, send_wecom_image

# 发送Markdown消息
await send_message(
    content="**Hello World!**",
    msg_type="markdown"
)

# 发送文本消息并提及用户
await send_message(
    content="Hello @user1 @user2",
    msg_type="text",
    mentioned_list=["user1", "user2"]
)

# 发送文件
await send_wecom_file("/path/to/file.txt")

# 发送图片
await send_wecom_image("/path/to/image.png")

开发

设置开发环境

克隆仓库：

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：

MR 检查：在所有拉取请求上运行，在Ubuntu、Windows和macOS上使用Python 3.10、3.11和3.12进行测试
代码覆盖率：上传覆盖率报告到Codecov
导入测试：确保安装后可以正确导入包

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

项目结构

wecom-bot-mcp-server/
├── src/
│   └── wecom_bot_mcp_server/
│       ├── __init__.py
│       ├── server.py
│       ├── message.py
│       ├── file.py
│       ├── image.py
│       ├── utils.py
│       └── errors.py
├── tests/
│   ├── test_server.py
│   ├── test_message.py
│   ├── test_file.py
│   └── test_image.py
├── docs/
├── pyproject.toml
├── noxfile.py
└── README.md

许可证

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

联系

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