企业微信机器人 MCP 服务端

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

smithery 徽章

English | 中文

功能特性

支持多种消息类型：
- 文本消息
- Markdown 消息
- 图片消息(base64编码)
- 文件消息
支持@提及功能(通过用户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"  # 自定义日志文件路径

日志管理

日志系统使用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 (text/markdown), mentioned_list, mentioned_mobile_list
send_file - 向企业微信发送文件
- 参数: file_path
send_image - 向企业微信发送图片
- 参数: 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:

合并请求检查: 在所有PR上运行，测试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