微信机器人MCP服务器

适用于 WeCom（企业微信）机器人的模型上下文协议 (MCP) 兼容服务器实现。

PyPI 版本 Python 版本代码验证代码风格：ruff 铁匠徽章

英语|中文

特征

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

Related MCP server: MCP Webhook Server

要求

Python 3.10+
WeCom Bot Webhook URL（从 WeCom 群设置中获取）

安装

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

1.自动安装（推荐）

使用 Smithery（适用于 Claude Desktop）：

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

使用带有 Cline 扩展的 VSCode：

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

2.手动安装

从 PyPI 安装：

pip install wecom-bot-mcp-server

手动配置 MCP：

创建或更新您的 MCP 配置文件：

// For Windsurf: ~/.windsurf/config.json
{
  "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

日志管理

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

Windows： C:\Users\<username>\AppData\Local\hal\wecom-bot-mcp-server
Linux： ~/.local/share/hal/wecom-bot-mcp-server
macOS： ~/Library/Application Support/hal/wecom-bot-mcp-server

日志文件名为mcp_wecom.log ，存储在上述目录中。

用法

启动服务器

wecom-bot-mcp-server

使用示例（使用 MCP）

# Scenario 1: Send weather information to 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"

await mcp.send_message(
    content="Shenzhen Weather:\n- Temperature: 25°C\n- Weather: Sunny\n- Air Quality: Good",
    msg_type="markdown"
)

# Scenario 2: Send meeting reminder and @mention relevant people
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"

await mcp.send_message(
    content="## Project Review Meeting Reminder\n\nTime: Today 3:00 PM\nLocation: Meeting Room A\n\nPlease be on time!",
    msg_type="markdown",
    mentioned_list=["zhangsan", "lisi"]
)

# Scenario 3: Send a file
USER: "Send this weekly report to the WeCom group"
ASSISTANT: "I'll send the weekly report"

await mcp.send_message(
    content=Path("weekly_report.docx"),
    msg_type="file"
)

直接使用 API

发送消息

from wecom_bot_mcp_server import mcp

# Send markdown message
await mcp.send_message(
    content="**Hello World!**", 
    msg_type="markdown"
)

# Send text message and mention users
await mcp.send_message(
    content="Hello @user1 @user2",
    msg_type="text",
    mentioned_list=["user1", "user2"]
)

发送文件

from wecom_bot_mcp_server import send_wecom_file

# Send file
await send_wecom_file("/path/to/file.txt")

发送图像

from wecom_bot_mcp_server import send_wecom_image

# Send local image
await send_wecom_image("/path/to/image.png")

# Send URL image
await send_wecom_image("https://example.com/image.png")

发展

设置开发环境

克隆存储库：

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]"

测试

# Using uv (recommended)
uvx nox -s pytest

# Or using traditional method
nox -s pytest

代码风格

# Check code
uvx nox -s lint

# Automatically fix code style issues
uvx nox -s lint_fix

构建和发布

# Build the package
uv build

# Build and publish to PyPI
uv build && twine upload dist/*

项目结构

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

WeCom Bot MCP Server