Skip to content
Back to search

wecom-bot-mcp-server

A Python server implementation for WeCom (WeChat Work) bot that follows the Model Context Protocol (MCP). This server provides a standardized interface for handling automated messaging and context-aware interactions within enterprise WeChat environments.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/loonghao--wecom-bot-mcp-server/badge.svg)](/listings/loonghao--wecom-bot-mcp-server)

HTML

<a href="/listings/loonghao--wecom-bot-mcp-server"><img src="/api/listings/loonghao--wecom-bot-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

There are several ways to install WeCom Bot MCP Server:

1. Automated Installation (Recommended)

Using Smithery (For Claude Desktop):

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

Using VSCode with Cline Extension:

1. Install [Cline Extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) from VSCode marketplace 2. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) 3. Search for "Cline: Install Package" 4. Type "wecom-bot-mcp-server" and press Enter

2. Manual Configuration

Add the server to your MCP client configuration file:

// 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"
      }
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 428 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/loonghao-wecom-bot-mcp-server-badge.png)](https://mseep.ai/app/loonghao-wecom-bot-mcp-server)
  2. # WeCom Bot MCP Server
  3. <div align="center">
  4. <img src="wecom.png" alt="WeCom Bot Logo" width="200"/>
  5. </div>
  6. A Model Context Protocol (MCP) compliant server implementation for WeCom (WeChat Work) bot.
  7. [![PyPI version](https://badge.fury.io/py/wecom-bot-mcp-server.svg)](https://badge.fury.io/py/wecom-bot-mcp-server)
  8. [![Python Version](https://img.shields.io/pypi/pyversions/wecom-bot-mcp-server.svg)](https://pypi.org/project/wecom-bot-mcp-server/)
  9. [![codecov](https://codecov.io/gh/loonghao/wecom-bot-mcp-server/branch/main/graph/badge.svg)](https://app.codecov.io/gh/loonghao/wecom-bot-mcp-server)
  10. [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
  11. [![smithery badge](https://smithery.ai/badge/wecom-bot-mcp-server)](https://smithery.ai/server/wecom-bot-mcp-server)
  12. [English](README.md) | [中文](README_zh.md)
  13. <a href="https://glama.ai/mcp/servers/amr2j23lbk"><img width="380" height="200" src="https://glama.ai/mcp/servers/amr2j23lbk/badge" alt="WeCom Bot Server MCP server" /></a>
  14. ## Features
  15. - Support for multiple message types:
  16. - Markdown messages (with @mentions and font colors)
  17. - Markdown V2 messages (with tables, lists, embedded images)
  18. - Image messages (base64/local file/URL)
  19. - File messages
  20. - Template card messages (text_notice and news_notice)
  21. - **Multi-bot support**: Configure and use multiple WeCom bots
  22. - @mention support (via user ID or phone number)
  23. - Message history tracking
  24. - Configurable logging system
  25. - Full type annotations
  26. - Pydantic-based data validation
  27. ## Requirements
  28. - Python 3.10+
  29. - WeCom Bot Webhook URL (obtained from WeCom group settings)
  30. ## Installation
  31. There are several ways to install WeCom Bot MCP Server:
  32. ### 1. Automated Installation (Recommended)
  33. #### Using Smithery (For Claude Desktop):
  34. ```bash
  35. npx -y @smithery/cli install wecom-bot-mcp-server --client claude
  36. ```
  37. #### Using VSCode with Cline Extension:
  38. 1. Install [Cline Extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) from VSCode marketplace
  39. 2. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
  40. 3. Search for "Cline: Install Package"
  41. 4. Type "wecom-bot-mcp-server" and press Enter
  42. ### 2. Manual Configuration
  43. Add the server to your MCP client configuration file:
  44. ```json
  45. // For Claude Desktop on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  46. // For Claude Desktop on Windows: %APPDATA%\Claude\claude_desktop_config.json
  47. // For Windsurf: ~/.windsurf/config.json
  48. // For Cline in VSCode: VSCode Settings > Cline > MCP Settings
  49. {
  50. "mcpServers": {
  51. "wecom": {
  52. "command": "uvx",
  53. "args": [
  54. "wecom-bot-mcp-server"
  55. ],
  56. "env": {
  57. "WECOM_WEBHOOK_URL": "your-webhook-url"
  58. }
  59. }
  60. }
  61. }
  62. ```
  63. ## Configuration
  64. ### Setting Environment Variables
  65. #### Single Bot (Default)
  66. ```bash
  67. # Windows PowerShell
  68. $env:WECOM_WEBHOOK_URL = "your-webhook-url"
  69. # Optional configurations
  70. $env:MCP_LOG_LEVEL = "DEBUG" # Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
  71. $env:MCP_LOG_FILE = "path/to/custom/log/file.log" # Custom log file path
  72. ```
  73. #### Multiple Bots Configuration
  74. You can configure multiple bots using any of these methods:
  75. **Method 1: JSON Configuration (Recommended)**
  76. ```bash
  77. # Windows PowerShell
  78. $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"}}'
  79. # Linux/macOS
  80. export WECOM_BOTS='{"alert": {"name": "Alert Bot", "webhook_url": "https://...", "description": "For alerts"}, "ci": {"name": "CI Bot", "webhook_url": "https://...", "description": "For CI/CD"}}'
  81. ```
  82. **Method 2: Individual Environment Variables**
  83. ```bash
  84. # Windows PowerShell
  85. $env:WECOM_BOT_ALERT_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
  86. $env:WECOM_BOT_CI_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=yyy"
  87. $env:WECOM_BOT_NOTIFY_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=zzz"
  88. ```
  89. **Method 3: Combined Mode**
  90. ```bash
  91. # WECOM_WEBHOOK_URL becomes the "default" bot
  92. $env:WECOM_WEBHOOK_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=default"
  93. # Additional bots
  94. $env:WECOM_BOT_ALERT_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=alert"
  95. ```
  96. #### MCP Client Configuration with Multiple Bots
  97. ```json
  98. {
  99. "mcpServers": {
  100. "wecom": {
  101. "command": "uvx",
  102. "args": ["wecom-bot-mcp-server"],
  103. "env": {
  104. "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=default",
  105. "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\"}}"
  106. }
  107. }
  108. }
  109. }
  110. ```
  111. ### Log Management
  112. The logging system uses `platformdirs.user_log_dir()` for cross-platform log file management:
  113. - Windows: `C:\Users\<username>\AppData\Local\hal\wecom-bot-mcp-server\Logs`
  114. - Linux: `~/.local/state/hal/wecom-bot-mcp-server/log`
  115. - macOS: `~/Library/Logs/hal/wecom-bot-mcp-server`
  116. The log file is named `mcp_wecom.log` and is stored in the above directory.
  117. You can customize the log level and file path using environment variables:
  118. - `MCP_LOG_LEVEL`: Set to DEBUG, INFO, WARNING, ERROR, or CRITICAL
  119. - `MCP_LOG_FILE`: Set to a custom log file path
  120. ## Usage
  121. Once configured, the MCP server runs automatically when your MCP client starts. You can interact with it through natural language in your AI assistant.
  122. ### Usage Examples
  123. **Scenario 1: Send weather information to WeCom**
  124. ```
  125. USER: "How's the weather in Shenzhen today? Send it to WeCom"
  126. ASSISTANT: "I'll check Shenzhen's weather and send it to WeCom"
  127. [The assistant will use the send_message tool to send the weather information]
  128. ```
  129. **Scenario 2: Send meeting reminder and @mention relevant people**
  130. ```
  131. USER: "Send a reminder for the 3 PM project review meeting, remind Zhang San and Li Si to attend"
  132. ASSISTANT: "I'll send the meeting reminder"
  133. [The assistant will use the send_message tool with mentioned_list parameter]
  134. ```
  135. **Scenario 3: Send a file**
  136. ```
  137. USER: "Send this weekly report to the WeCom group"
  138. ASSISTANT: "I'll send the weekly report"
  139. [The assistant will use the send_file tool]
  140. ```
  141. **Scenario 4: Send an image**
  142. ```
  143. USER: "Send this chart image to WeCom"
  144. ASSISTANT: "I'll send the image"
  145. [The assistant will use the send_image tool]
  146. ```
  147. ### Available MCP Tools
  148. The server provides the following tools that your AI assistant can use:
  149. 1. **send_message** - Send text or markdown messages
  150. - Parameters: `content`, `msg_type` (markdown/markdown_v2), `mentioned_list`, `mentioned_mobile_list`, `bot_id`
  151. - `markdown`: Use when content contains `<@userid>` mentions or font colors. The `<@userid>` syntax is WeCom's official mention format, which avoids conflicts with email addresses like `@user@email.com`
  152. - `markdown_v2`: Use for tables, lists, embedded images, or general content (default)
  153. 2. **send_wecom_file** - Send files to WeCom
  154. - Parameters: `file_path`, `bot_id`
  155. 3. **send_wecom_image** - Send images to WeCom
  156. - Parameters: `image_path` (local path or URL), `bot_id`
  157. 4. **send_wecom_template_card_text_notice** - Send text notice template card
  158. - Parameters: `template_card_source`, `template_card_main_title`, `template_card_card_action`, `bot_id`, and optional fields
  159. - Use for notifications with emphasis content, quotes, and action buttons
  160. 5. **send_wecom_template_card_news_notice** - Send news notice template card
  161. - Parameters: `template_card_source`, `template_card_main_title`, `template_card_card_action`, `template_card_image`, `bot_id`, and optional fields
  162. - Use for news-style notifications with images and rich content
  163. 6. **list_wecom_bots** - List all configured bots
  164. - Returns: List of available bots with their IDs, names, and descriptions
  165. ### Multi-Bot Usage Examples
  166. **Scenario 5: Send alert to specific bot**
  167. ```
  168. USER: "Send a critical alert to the alert bot: Server CPU usage is above 90%"
  169. ASSISTANT: "I'll send the alert to the alert bot"
  170. [The assistant will use send_message with bot_id="alert"]
  171. ```
  172. **Scenario 6: List available bots**
  173. ```
  174. USER: "What WeCom bots are available?"
  175. ASSISTANT: "Let me check the available bots"
  176. [The assistant will use list_wecom_bots tool]
  177. ```
  178. **Scenario 7: Send CI notification**
  179. ```
  180. USER: "Send build success notification to the CI bot"
  181. ASSISTANT: "I'll send the notification to the CI bot"
  182. [The assistant will use send_message with bot_id="ci"]
  183. ```
  184. **Scenario 8: Send template card notification**
  185. ```
  186. USER: "Send a deployment success notification card with a link to the dashboard"
  187. ASSISTANT: "I'll send a template card notification"
  188. [The assistant will use send_wecom_template_card_text_notice tool]
  189. ```
  190. **Scenario 9: Send news-style notification**
  191. ```
  192. USER: "Send a news card about the new feature release with an image"
  193. ASSISTANT: "I'll send a news notice card"
  194. [The assistant will use send_wecom_template_card_news_notice tool]
  195. ```
  196. ### For Developers: Direct API Usage
  197. If you want to use this package directly in your Python code (not as an MCP server):
  198. ```python
  199. from wecom_bot_mcp_server import send_message, send_wecom_file, send_wecom_image, send_wecom_template_card
  200. # Send markdown message (uses default bot)
  201. await send_message(content="**Hello World!**", msg_type="markdown")
  202. # Send markdown_v2 message with tables and lists (default)
  203. await send_message(
  204. content="| Column1 | Column2 |\n|---------|---------|\\n| Value1 | Value2 |", msg_type="markdown_v2"
  205. )
  206. # Send text message and mention users (use markdown for @mentions)
  207. await send_message(content="Hello <@user1> <@user2>", msg_type="markdown", mentioned_list=["user1", "user2"])
  208. # Send message to a specific bot
  209. await send_message(
  210. content="Build completed successfully!",
  211. msg_type="markdown_v2",
  212. bot_id="ci", # Send to CI bot
  213. )
  214. # Send alert to alert bot
  215. await send_message(content="⚠️ High CPU usage detected!", msg_type="markdown_v2", bot_id="alert")
  216. # Send file to specific bot
  217. await send_wecom_file("/path/to/file.txt", bot_id="ci")
  218. # Send image to specific bot
  219. await send_wecom_image("/path/to/image.png", bot_id="alert")
  220. # Send template card (text_notice)
  221. await send_wecom_template_card(
  222. template_card_type="text_notice",
  223. template_card_source={"icon_url": "https://example.com/icon.png", "desc": "System"},
  224. template_card_main_title={"title": "Deployment Success", "desc": "Production environment"},
  225. template_card_card_action={"type": 1, "url": "https://example.com/dashboard"},
  226. template_card_emphasis_content={"title": "100%", "desc": "Success Rate"},
  227. bot_id="ci",
  228. )
  229. ```
  230. ### Multi-Bot Configuration in Code
  231. ```python
  232. from wecom_bot_mcp_server.bot_config import get_bot_registry, list_available_bots
  233. # List all available bots
  234. bots = list_available_bots()
  235. for bot in bots:
  236. print(f"Bot: {bot['id']} - {bot['name']}")
  237. # Check if a specific bot exists
  238. registry = get_bot_registry()
  239. if registry.has_bot("alert"):
  240. print("Alert bot is configured")
  241. # Get webhook URL for a specific bot
  242. url = registry.get_webhook_url("ci")
  243. ```
  244. ## Development
  245. ### Setup Development Environment
  246. 1. Clone the repository:
  247. ```bash
  248. git clone https://github.com/loonghao/wecom-bot-mcp-server.git
  249. cd wecom-bot-mcp-server
  250. ```
  251. 2. Create a virtual environment and install dependencies:
  252. ```bash
  253. # Using uv (recommended)
  254. pip install uv
  255. uv venv
  256. uv pip install -e ".[dev]"
  257. # Or using traditional method
  258. python -m venv venv
  259. source venv/bin/activate # On Windows: venv\Scripts\activate
  260. pip install -e ".[dev]"
  261. ```
  262. ### Testing
  263. ```bash
  264. # Run all tests with coverage
  265. uvx nox -s pytest
  266. # Run import tests only
  267. uvx nox -s test_imports
  268. # Run specific test file
  269. uvx nox -s pytest -- tests/test_message.py
  270. # Run tests with verbose output
  271. uvx nox -s pytest -- -v
  272. ```
  273. ### Code Style
  274. ```bash
  275. # Check code
  276. uvx nox -s lint
  277. # Automatically fix code style issues
  278. uvx nox -s lint_fix
  279. ```
  280. ### Building and Publishing
  281. ```bash
  282. # Build the package
  283. uvx nox -s build
  284. # Publish to PyPI (requires authentication)
  285. uvx nox -s publish
  286. ```
  287. ### Continuous Integration
  288. The project uses GitHub Actions for CI/CD:
  289. - **MR Checks**: Runs on all pull requests, tests on Ubuntu, Windows, and macOS with Python 3.10, 3.11, and 3.12
  290. - **Code Coverage**: Uploads coverage reports to Codecov
  291. - **Import Tests**: Ensures the package can be imported correctly after installation
  292. All dependencies are automatically tested during CI to catch issues early.
  293. ## Project Structure
  294. ```
  295. wecom-bot-mcp-server/
  296. ├── src/
  297. │ └── wecom_bot_mcp_server/
  298. │ ├── __init__.py
  299. │ ├── __main__.py
  300. │ ├── __version__.py
  301. │ ├── app.py # FastMCP application setup
  302. │ ├── server.py # Server entry point
  303. │ ├── message.py # Message and template card handling
  304. │ ├── file.py # File upload handling
  305. │ ├── image.py # Image upload handling
  306. │ ├── bot_config.py # Multi-bot configuration
  307. │ ├── utils.py # Utility functions
  308. │ ├── log_config.py # Logging configuration
  309. │ └── errors.py # Error definitions
  310. ├── tests/
  311. │ ├── test_server.py
  312. │ ├── test_message.py
  313. │ ├── test_file.py
  314. │ ├── test_image.py
  315. │ └── test_bot_config.py
  316. ├── docs/
  317. ├── pyproject.toml
  318. ├── noxfile.py
  319. └── README.md
  320. ```
  321. ## License
  322. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  323. ## Contact
  324. - Author: longhao
  325. - Email: hal.long@outlook.com

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.