WeCom MCP Server

A Python-based MCP (Model Context Protocol) Server for WeCom (WeChat Work / 企业微信) self-built applications.

Provides a standard set of MCP tools that enable AI Agents (e.g., Trae Work, Claude Desktop) to send messages to WeCom users/departments, query contacts, receive and store messages, and more.

🌐 中文版 (Chinese)

✨ Features

Core Capabilities

• 📨 Message Sending: Text, Markdown, generic message bodies, file sending, and @all mass messaging
• 📇 Contact Lookup: Quickly find UserIDs by member name, or batch-retrieve members by department
• 📥 Message Reception: In HTTP mode, automatically listens for WeCom callbacks and persists received messages to SQLite in real time
• 🔍 History Query: Query historical messages by time, type, sender, keywords, and more
• 🗄️ File Management: Received images/voice/video/files are automatically downloaded to local disk with metadata stored in the database

Technical Highlights

• Pure-Python AES-256-CBC: No dependency on the cryptography library, avoiding native compilation issues on certain platforms
• Multiple Transport Support: stdio (single Agent), streamable-http (shared by multiple Agents), sse (legacy compatibility)
• SQLite Yearly Partitioning: Automatically splits data tables by calendar year to prevent single-table bloat
• Managed by uv: Ultra-fast package manager and virtual environment

🛠️ MCP Tool List

Universal Tools (Stdio & HTTP/SSE)

Tool Name	Description
send_text_message	Send a text message
send_markdown_message	Send a Markdown message
send_message	Send any type of message (text/markdown/news, etc.)
send_file_message	Send a local file (auto-upload)
mass_send_message	Mass message all members in the app's visible scope (@all)
lookup_user_id	Find UserID by member name
list_users_by_department	List all members in a department (including sub-departments)
check_config	Check current WeCom configuration status

HTTP/SSE Exclusive Tools

Tool Name	Description
health_check	Health check (Webhook status, database status, etc.)
search_history_messages	Query historical messages (filter by time/type/sender/keywords)
get_message_detail	Get details of a single message
get_message_file	Get the local file path associated with a message
list_message_years	List years that have historical data
get_message_stats	Historical message statistics (by type/sender/month)

🚀 Quick Start

1. Requirements

• Python >= 3.14
• uv package manager

2. Installation & Configuration

# Clone the project
git clone <your-repo-url>
cd wecom-mcp-server

# Create virtual environment and install dependencies
uv sync

# Copy the environment variable template
cp .env.example .env

3. Configuration

Edit .env and fill in your WeCom self-built application credentials:

# Corp ID
WECOM_CORP_ID=ww1234567890abcdef

# Self-built App Secret
WECOM_CORP_SECRET=your_app_secret

# Self-built App AgentId (number)
WECOM_AGENT_ID=1000002

# ====== Optional ======

# Contacts Sync Secret (recommended for full-directory access)
WECOM_CONTACTS_SECRET=your_contacts_secret

# Message callback (only needed for receiving messages / history query)
WECOM_CALLBACK_TOKEN=your_callback_token
WECOM_CALLBACK_ENCODING_AES_KEY=your_aes_key_43_chars_long

# MCP service mode
# stdio: default, single-client local calls
# streamable-http: HTTP service, shared by multiple Agents
# sse: legacy SSE mode
WECOM_MCP_TRANSPORT=streamable-http
WECOM_MCP_HOST=0.0.0.0
WECOM_MCP_PORT=9000

# Data persistence directory
WECOM_DATA_DIR=data

4. Run

Mode 1: Stdio (for Trae Work)

Add to your Trae Work MCP configuration:

{
  "mcpServers": {
    "wecom": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/wecom-mcp-server", "wecom-mcp-server"]
    }
  }
}

Mode 2: HTTP Service (shared by multiple Agents)

# Run in foreground
uv run wecom-mcp-server --transport streamable-http --host 0.0.0.0 --port 9000

# Or use .env configuration
WECOM_MCP_TRANSPORT=streamable-http WECOM_MCP_PORT=9000 uv run wecom-mcp-server

Callers interact with the MCP Server via HTTP:

curl -X POST http://localhost:9000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "send_text_message", "arguments": {"to_user": "zhangsan", "content": "Hello!"}}}'

⚙️ Supervisor Deployment

To keep the service running in the background, use supervisord.

Config file: /usr/local/etc/supervisor.d/wecom-mcp-server.conf

[program:wecom-mcp-server]
command=/usr/local/bin/uv run wecom-mcp-server --transport streamable-http --host 0.0.0.0 --port 9000
directory=/path/to/wecom-mcp-server
user=your_username
autostart=true
autorestart=true
startretries=3
stopasgroup=true
killasgroup=true
stderr_logfile=/path/to/logs/wecom-mcp-server.err.log
stdout_logfile=/path/to/logs/wecom-mcp-server.out.log
environment=LANG="en_US.UTF-8",PATH="/usr/local/bin:/usr/bin:/bin"

Common commands:

supervisorctl reread            # Reload configuration
supervisorctl update            # Update process groups
supervisorctl status            # View all service statuses
supervisorctl restart wecom-mcp-server  # Restart service

📁 Project Structure

wecom-mcp-server/
├── src/
│   └── wecom_mcp_server/
│       ├── __init__.py
│       ├── server.py          # MCP Server entry point, tool registration
│       ├── config.py          # Configuration management (pydantic-settings)
│       ├── aes.py             # Pure-Python AES-256-CBC implementation
│       ├── crypto.py          # WeCom message encryption/decryption logic
│       ├── wecom_client.py    # WeCom API async client
│       ├── webhook.py         # Message reception webhook service
│       └── storage.py         # SQLite message persistence & file management
├── .env.example               # Environment variable example
├── pyproject.toml             # Project dependencies & build config
└── README.md                  # This document

🔑 Configuration Notes

WeCom App Permissions

1. Basic Sending Permission: Create a self-built app in the WeCom admin backend and obtain CorpID, Secret, and AgentId.
2. Contact Reading Permission (optional): Enable API Interface Sync in "Management Tools → Contact Sync" to get contacts_secret. Without it, only members within the app's visible scope can be read.
3. Message Reception (optional): Enable API reception in the app's "Receive Messages" settings to get Token and EncodingAESKey. For local development, use an intranet tunnel tool (e.g., ngrok, cloudflared) to expose the callback address.

Data Storage Structure

data/
├── wecom_messages.db          # SQLite database (yearly partitioned tables)
└── files/
    ├── 2026/
    │   ├── 07/
    │   │   ├── image_xxx.jpg
    │   │   └── report.pdf
    │   └── ...
    └── ...

📜 License

MIT