WeCom MCP Server

Social Preview

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

Basic Sending Permission: Create a self-built app in the WeCom admin backend and obtain CorpID, Secret, and AgentId.
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.
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

WeCom MCP Server

WeCom MCP Server

✨ Features

Core Capabilities

Technical Highlights

🛠️ MCP Tool List

Universal Tools (Stdio & HTTP/SSE)

HTTP/SSE Exclusive Tools

🚀 Quick Start

1. Requirements

2. Installation & Configuration

3. Configuration

4. Run

Mode 1: Stdio (for Trae Work)

Mode 2: HTTP Service (shared by multiple Agents)

⚙️ Supervisor Deployment

📁 Project Structure

🔑 Configuration Notes

WeCom App Permissions

Data Storage Structure

📜 License

Latest Blog Posts

MCP directory API