[](https://mseep.ai/app/loonghao-wecom-bot-mcp-server)
# WeCom Bot MCP Server
<div align="center">
<img src="wecom.png" alt="WeCom Bot Logo" width="200"/>
</div>
A Model Context Protocol (MCP) compliant server implementation for WeCom (WeChat Work) bot.
[](https://badge.fury.io/py/wecom-bot-mcp-server)
[](https://pypi.org/project/wecom-bot-mcp-server/)
[](https://app.codecov.io/gh/loonghao/wecom-bot-mcp-server)
[](https://github.com/astral-sh/ruff)
[](https://smithery.ai/server/wecom-bot-mcp-server)
[English](README.md) | [中文](README_zh.md)
<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>
## Features
- Support for multiple message types:
- Text messages
- Markdown messages
- Image messages (base64)
- File messages
- @mention support (via user ID or phone number)
- Message history tracking
- Configurable logging system
- Full type annotations
- Pydantic-based data validation
## Requirements
- Python 3.10+
- WeCom Bot Webhook URL (obtained from WeCom group settings)
## Installation
There are several ways to install WeCom Bot MCP Server:
### 1. Automated Installation (Recommended)
#### Using Smithery (For Claude Desktop):
```bash
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 Installation
#### Install from PyPI:
```bash
pip install wecom-bot-mcp-server
```
#### Configure MCP manually:
Create or update your MCP configuration file:
```json
// For Windsurf: ~/.windsurf/config.json
{
"mcpServers": {
"wecom": {
"command": "uvx",
"args": [
"wecom-bot-mcp-server"
],
"env": {
"WECOM_WEBHOOK_URL": "your-webhook-url"
}
}
}
}
```
## Configuration
### Setting Environment Variables
```bash
# 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
```
### Log Management
The logging system uses `platformdirs.user_log_dir()` for cross-platform log file management:
- 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`
The log file is named `mcp_wecom.log` and is stored in the above directory.
## Usage
### Starting the Server
```bash
wecom-bot-mcp-server
```
### Usage Examples (With MCP)
```python
# 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"
)
```
### Direct API Usage
#### Send Messages
```python
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"]
)
```
#### Send Files
```python
from wecom_bot_mcp_server import send_wecom_file
# Send file
await send_wecom_file("/path/to/file.txt")
```
#### Send Images
```python
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")
```
## Development
### Setup Development Environment
1. Clone the repository:
```bash
git clone https://github.com/loonghao/wecom-bot-mcp-server.git
cd wecom-bot-mcp-server
```
2. Create a virtual environment and install dependencies:
```bash
# 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]"
```
### Testing
```bash
# Using uv (recommended)
uvx nox -s pytest
# Or using traditional method
nox -s pytest
```
### Code Style
```bash
# Check code
uvx nox -s lint
# Automatically fix code style issues
uvx nox -s lint_fix
```
### Building and Publishing
```bash
# Build the package
uv build
# Build and publish to PyPI
uv build && twine upload dist/*
```
## Project Structure
```
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
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Contact
- Author: longhao
- Email: hal.long@outlook.com
Raw data
{
"_id": null,
"home_page": null,
"name": "wecom-bot-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "longhao",
"author_email": "hal.long@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/e8/b6/83d608d9f424730e58039e00370052aab5b79d7d23eb83dcf68650852a63/wecom_bot_mcp_server-0.6.14.tar.gz",
"platform": null,
"description": "[](https://mseep.ai/app/loonghao-wecom-bot-mcp-server)\n\n# WeCom Bot MCP Server\n\n<div align=\"center\">\n <img src=\"wecom.png\" alt=\"WeCom Bot Logo\" width=\"200\"/>\n</div>\n\nA Model Context Protocol (MCP) compliant server implementation for WeCom (WeChat Work) bot.\n\n[](https://badge.fury.io/py/wecom-bot-mcp-server)\n[](https://pypi.org/project/wecom-bot-mcp-server/)\n[](https://app.codecov.io/gh/loonghao/wecom-bot-mcp-server)\n[](https://github.com/astral-sh/ruff)\n[](https://smithery.ai/server/wecom-bot-mcp-server)\n\n[English](README.md) | [\u4e2d\u6587](README_zh.md)\n\n<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>\n\n## Features\n\n- Support for multiple message types:\n - Text messages\n - Markdown messages\n - Image messages (base64)\n - File messages\n- @mention support (via user ID or phone number)\n- Message history tracking\n- Configurable logging system\n- Full type annotations\n- Pydantic-based data validation\n\n## Requirements\n\n- Python 3.10+\n- WeCom Bot Webhook URL (obtained from WeCom group settings)\n\n## Installation\n\nThere are several ways to install WeCom Bot MCP Server:\n\n### 1. Automated Installation (Recommended)\n\n#### Using Smithery (For Claude Desktop):\n\n```bash\nnpx -y @smithery/cli install wecom-bot-mcp-server --client claude\n```\n\n#### Using VSCode with Cline Extension:\n\n1. Install [Cline Extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) from VSCode marketplace\n2. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)\n3. Search for \"Cline: Install Package\"\n4. Type \"wecom-bot-mcp-server\" and press Enter\n\n### 2. Manual Installation\n\n#### Install from PyPI:\n\n```bash\npip install wecom-bot-mcp-server\n```\n\n#### Configure MCP manually:\n\nCreate or update your MCP configuration file:\n\n```json\n// For Windsurf: ~/.windsurf/config.json\n{\n \"mcpServers\": {\n \"wecom\": {\n \"command\": \"uvx\",\n \"args\": [\n \"wecom-bot-mcp-server\"\n ],\n \"env\": {\n \"WECOM_WEBHOOK_URL\": \"your-webhook-url\"\n }\n }\n }\n}\n```\n\n## Configuration\n\n### Setting Environment Variables\n\n```bash\n# Windows PowerShell\n$env:WECOM_WEBHOOK_URL = \"your-webhook-url\"\n\n# Optional configurations\n$env:MCP_LOG_LEVEL = \"DEBUG\" # Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL\n$env:MCP_LOG_FILE = \"path/to/custom/log/file.log\" # Custom log file path\n```\n\n### Log Management\n\nThe logging system uses `platformdirs.user_log_dir()` for cross-platform log file management:\n\n- Windows: `C:\\Users\\<username>\\AppData\\Local\\hal\\wecom-bot-mcp-server`\n- Linux: `~/.local/share/hal/wecom-bot-mcp-server`\n- macOS: `~/Library/Application Support/hal/wecom-bot-mcp-server`\n\nThe log file is named `mcp_wecom.log` and is stored in the above directory.\n\n## Usage\n\n### Starting the Server\n\n```bash\nwecom-bot-mcp-server\n```\n\n### Usage Examples (With MCP)\n\n```python\n# Scenario 1: Send weather information to WeCom\nUSER: \"How's the weather in Shenzhen today? Send it to WeCom\"\nASSISTANT: \"I'll check Shenzhen's weather and send it to WeCom\"\n\nawait mcp.send_message(\n content=\"Shenzhen Weather:\\n- Temperature: 25\u00b0C\\n- Weather: Sunny\\n- Air Quality: Good\",\n msg_type=\"markdown\"\n)\n\n# Scenario 2: Send meeting reminder and @mention relevant people\nUSER: \"Send a reminder for the 3 PM project review meeting, remind Zhang San and Li Si to attend\"\nASSISTANT: \"I'll send the meeting reminder\"\n\nawait mcp.send_message(\n content=\"## Project Review Meeting Reminder\\n\\nTime: Today 3:00 PM\\nLocation: Meeting Room A\\n\\nPlease be on time!\",\n msg_type=\"markdown\",\n mentioned_list=[\"zhangsan\", \"lisi\"]\n)\n\n# Scenario 3: Send a file\nUSER: \"Send this weekly report to the WeCom group\"\nASSISTANT: \"I'll send the weekly report\"\n\nawait mcp.send_message(\n content=Path(\"weekly_report.docx\"),\n msg_type=\"file\"\n)\n```\n\n### Direct API Usage\n\n#### Send Messages\n\n```python\nfrom wecom_bot_mcp_server import mcp\n\n# Send markdown message\nawait mcp.send_message(\n content=\"**Hello World!**\", \n msg_type=\"markdown\"\n)\n\n# Send text message and mention users\nawait mcp.send_message(\n content=\"Hello @user1 @user2\",\n msg_type=\"text\",\n mentioned_list=[\"user1\", \"user2\"]\n)\n```\n\n#### Send Files\n\n```python\nfrom wecom_bot_mcp_server import send_wecom_file\n\n# Send file\nawait send_wecom_file(\"/path/to/file.txt\")\n```\n\n#### Send Images\n\n```python\nfrom wecom_bot_mcp_server import send_wecom_image\n\n# Send local image\nawait send_wecom_image(\"/path/to/image.png\")\n\n# Send URL image\nawait send_wecom_image(\"https://example.com/image.png\")\n```\n\n## Development\n\n### Setup Development Environment\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/loonghao/wecom-bot-mcp-server.git\ncd wecom-bot-mcp-server\n```\n\n2. Create a virtual environment and install dependencies:\n```bash\n# Using uv (recommended)\npip install uv\nuv venv\nuv pip install -e \".[dev]\"\n\n# Or using traditional method\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\npip install -e \".[dev]\"\n```\n\n### Testing\n\n```bash\n# Using uv (recommended)\nuvx nox -s pytest\n\n# Or using traditional method\nnox -s pytest\n```\n\n### Code Style\n\n```bash\n# Check code\nuvx nox -s lint\n\n# Automatically fix code style issues\nuvx nox -s lint_fix\n```\n\n### Building and Publishing\n\n```bash\n# Build the package\nuv build\n\n# Build and publish to PyPI\nuv build && twine upload dist/*\n```\n\n## Project Structure\n\n```\nwecom-bot-mcp-server/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 wecom_bot_mcp_server/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 server.py\n\u2502 \u251c\u2500\u2500 message.py\n\u2502 \u251c\u2500\u2500 file.py\n\u2502 \u251c\u2500\u2500 image.py\n\u2502 \u251c\u2500\u2500 utils.py\n\u2502 \u2514\u2500\u2500 errors.py\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 test_server.py\n\u2502 \u251c\u2500\u2500 test_message.py\n\u2502 \u251c\u2500\u2500 test_file.py\n\u2502 \u2514\u2500\u2500 test_image.py\n\u251c\u2500\u2500 docs/\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 noxfile.py\n\u2514\u2500\u2500 README.md\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contact\n\n- Author: longhao\n- Email: hal.long@outlook.com\n\n",
"bugtrack_url": null,
"license": null,
"summary": "WeCom Bot MCP Server - A Python server for WeCom (WeChat Work) bot following the Model Context Protocol (MCP)",
"version": "0.6.14",
"project_urls": {
"Homepage": "https://github.com/loonghao/wecom-bot-mcp-server",
"Issues": "https://github.com/loonghao/wecom-bot-mcp-server/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ed3e6c9cf2ee52c146765f89b2a0a0075a382d657a3fd77805c8f97b968fcbca",
"md5": "62d54bb9bfabdc74ad6a0ba50a059411",
"sha256": "e04aedfe4221efb7791e7f2fc3abf42cf1e0e6610f3817b62e67f767d53936b1"
},
"downloads": -1,
"filename": "wecom_bot_mcp_server-0.6.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62d54bb9bfabdc74ad6a0ba50a059411",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 16015,
"upload_time": "2025-08-27T17:53:08",
"upload_time_iso_8601": "2025-08-27T17:53:08.484199Z",
"url": "https://files.pythonhosted.org/packages/ed/3e/6c9cf2ee52c146765f89b2a0a0075a382d657a3fd77805c8f97b968fcbca/wecom_bot_mcp_server-0.6.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e8b683d608d9f424730e58039e00370052aab5b79d7d23eb83dcf68650852a63",
"md5": "83938f20d0644db1a76b1e2e051180e7",
"sha256": "7604bc9ee217d336a86215417eef25ddc060ad13e466902d4b1fedcaa392ca6e"
},
"downloads": -1,
"filename": "wecom_bot_mcp_server-0.6.14.tar.gz",
"has_sig": false,
"md5_digest": "83938f20d0644db1a76b1e2e051180e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 14062,
"upload_time": "2025-08-27T17:53:09",
"upload_time_iso_8601": "2025-08-27T17:53:09.612576Z",
"url": "https://files.pythonhosted.org/packages/e8/b6/83d608d9f424730e58039e00370052aab5b79d7d23eb83dcf68650852a63/wecom_bot_mcp_server-0.6.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 17:53:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "loonghao",
"github_project": "wecom-bot-mcp-server",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "notify-bridge",
"specs": [
[
">=",
"0.3.0"
]
]
},
{
"name": "uvicorn",
"specs": [
[
">=",
"0.34.0"
]
]
},
{
"name": "platformdirs",
"specs": [
[
">=",
"4.2.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.6.1"
]
]
},
{
"name": "ftfy",
"specs": [
[
">=",
"6.3.1"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.28.1"
]
]
},
{
"name": "pillow",
"specs": [
[
">=",
"10.2.0"
]
]
},
{
"name": "svglib",
"specs": [
[
">=",
"1.5.1"
]
]
},
{
"name": "circuitbreaker",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "tenacity",
"specs": [
[
">=",
"9.0.0"
]
]
},
{
"name": "loguru",
"specs": [
[
">=",
"0.7.3"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.11.13"
]
]
},
{
"name": "backoff",
"specs": [
[
">=",
"2.2.1"
]
]
}
],
"lcname": "wecom-bot-mcp-server"
}
JSON
