<div align="center">
# WeChat MCP Server
[](https://www.python.org/downloads/)
[](https://pypi.org/project/wechat-mcp-server/)
[](https://opensource.org/licenses/MIT)
[δΈζ](docs/README_zh.md) | English
</div>
An MCP server that automates WeChat on macOS using the Accessibility API and screen capture. It enables LLMs to interact with WeChat chats programmatically.
## Features
- π¨ Fetch recent messages from any chat (contact or group)
- βοΈ Send automated replies based on chat history
- π· Publish text-only Moments posts, with optional draft-only mode
- π₯ Add contacts using WeChat ID with configurable privacy
- π Smart chat search with exact name matching
- π€ 5 specialized Claude Code sub-agents for smart WeChat automation
## Quick Start
### Installation
```bash
pip install wechat-mcp-server
```
### Setup with Claude Code
```bash
# If installed via pip
claude mcp add --transport stdio wechat-mcp -- wechat-mcp
# If using uv for development
claude mcp add --transport stdio wechat-mcp -- uv --directory $(pwd) run wechat-mcp
```
<details>
<summary>Setup with Claude Desktop</summary>
```json
// If installed via pip
{
"mcpServers": {
"wechat-mcp": {
"type": "stdio",
"command": "wechat-mcp"
}
}
}
// If using uv for development
{
"mcpServers": {
"wechat-mcp": {
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"{path/to/wechat-mcp}",
"run",
"wechat-mcp"
],
}
}
}
```
</details>
<details>
<summary>Setup with Codex</summary>
```bash
# If installed via pip
codex mcp add wechat-mcp -- wechat-mcp
# If using uv for development
codex mcp add wechat-mcp -- uv --directory $(pwd) run wechat-mcp
```
</details>
### macOS Permissions
β οΈ **Important**: Grant Accessibility permissions to your terminal:
1. Open **System Settings β Privacy & Security β Accessibility**
2. Add your terminal application (Terminal.app, iTerm2, etc.)
3. Ensure WeChat is running before using the server
## Usage
### Basic Commands
```bash
# Run with default stdio transport
wechat-mcp --transport stdio
# Run with HTTP transport
wechat-mcp --transport streamable-http
# Run with SSE transport
wechat-mcp --transport sse
```
### Available MCP Tools
- **`fetch_messages_by_chat`** - Get recent messages from a chat
- **`reply_to_messages_by_chat`** - Send a reply to a chat
- **`add_contact_by_wechat_id`** - Add a new contact using a WeChat ID and send a friend request
- **`publish_moment_without_media`** - Publish a text-only Moments post (no photos or videos); optionally only prepare a draft without posting via `publish=False`
See [detailed API documentation](docs/detailed-guide.md) for full tool specifications.
## Claude Code Sub-Agents
This project includes 5 intelligent sub-agents designed specifically for WeChat automation. They enable natural language control of WeChat through Claude Code.
### Available Sub-Agents
1. **Chat-summarizer** - Summarize chat history and extract key information
2. **Auto-replier** - Auto-generate and send appropriate replies
3. **Message-searcher** - Search chat history for specific content
4. **Multi-chat-checker** - Monitor multiple chats and prioritize messages
5. **Chat-insights** - Analyze relationship dynamics and communication patterns
π [View complete sub-agents guide](.claude/agents/README.md)
## Development
### Local Setup with uv
```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone and setup
git clone https://github.com/yourusername/WeChat-MCP.git
cd WeChat-MCP
uv sync
# Run locally
uv run wechat-mcp --transport stdio
```
## Documentation
- π [Detailed Guide](docs/detailed-guide.md) - Complete API documentation and architecture
- π€ [Sub-Agents Guide](.claude/agents/README.md) - How to use Claude Code sub-agents
## Requirements
- macOS (uses Accessibility API)
- WeChat for Mac installed and running
- Python 3.12+
- Accessibility permissions for terminal
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License - see [LICENSE](LICENSE) file for details
