wechat-mcp-server
Allows reading WeChat chat records, contacts, sessions, favorites, and extracting personal communication style from chat logs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@wechat-mcp-server Show my last 5 messages from work group"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
wechat-mcp-server
一个用于读取本机微信数据的 MCP Server:让 Claude Code 等 AI 助手可以通过 MCP 工具读取聊天记录/会话/联系人/收藏等。
功能特性
查询微信聊天记录、联系人、会话列表、收藏等
Skill 蒸馏:从聊天记录提取个人沟通风格(统计 + Few-shot + 可生成系统提示词)
消息监听:近实时获取新消息(轮询会话数据库)
表情包管理:解析表情消息、构建表情包库,并支持解析
[sticker:xxx]占位符
Related MCP server: WeChat Local Agent MCP
安装
# 克隆并安装
git clone <repo-url>
cd wechat-mcp-server
pip install -e .初始化(首次必做)
首次使用需要提取微信数据库解密密钥(会写入到 ~/.wechat-cli/all_keys.json):
wechat-cli-mcp init你也可以手动指定微信数据目录(db_storage):
wechat-cli-mcp init --db-dir "D:\\...\\db_storage"重要提示(务必看)
初始化时必须保证微信正在运行(Windows 为
Weixin.exe),否则无法从进程内存提取密钥。权限问题:部分系统/环境下可能需要管理员权限运行终端。
只读原则:本项目只读取/解析数据,不包含“发送消息”能力。
密钥文件位置:默认使用
~/.wechat-cli/all_keys.json。删除该文件后需要重新执行init。
启动 MCP Server
你有 3 种方式启动(任选其一):
方式一:安装后直接启动(推荐)
安装 pip install -e . 后,会安装命令行入口:
wechat-cli-mcpWindows 下推荐使用 SSE 模式(更稳定):
wechat-cli-mcp --sse或通过环境变量:
MCP_TRANSPORT=sse wechat-cli-mcp启动后会显示:
INFO: Uvicorn running on http://127.0.0.1:8000方式二:配置到 Claude Code
在你的 .mcp.json 添加:
{
"mcpServers": {
"wechat-cli-mcp": {
"type": "stdio",
"command": "wechat-cli-mcp"
}
}
}Windows 下推荐使用 SSE 配置:
{
"mcpServers": {
"wechat-cli-mcp": {
"type": "sse",
"url": "http://127.0.0.1:8000/sse"
}
}
}或使用 Claude CLI:
claude mcp add wechat-cli-mcp -- wechat-cli-mcp注意:如果使用 SSE 模式,需要先手动启动 server(方式一),然后再配置 IDE 连接。
方式三:用 Python 模块启动
python -m wechat_cli_mcpWindows 下加 SSE 参数:
python -m wechat_cli_mcp --sse工具列表(MCP Tools)
基础查询工具
工具 | 说明 |
| 列出最近聊天会话 |
| 读取指定会话的聊天记录 |
| 按关键词搜索消息 |
| 搜索联系人 |
| 未读会话 |
| 增量获取新消息(自上次检查之后) |
| 群成员列表 |
| 会话统计 |
| 收藏/书签 |
Skill 蒸馏工具
工具 | 说明 |
| 从聊天记录蒸馏个人沟通风格(返回 JSON 或 Markdown) |
| 蒸馏并保存到文件(JSON 或 Markdown) |
示例:
# 从多个会话蒸馏
wechat_distill_skill(chat_names="张三,李四,工作群", message_limit=500)
# 保存为 Markdown
wechat_save_skill(chat_names="张三", output_path="my_style.md", output_format="markdown")消息监听工具
工具 | 说明 |
| 启动监听(近实时) |
| 停止监听 |
| 查看监听状态 |
| 获取监听缓冲的新消息 |
说明:监听器会轮询会话数据库的最新时间戳来发现新消息,并将新消息缓冲到内存中供工具读取。
示例:
wechat_start_listener(interval=0.5)
wechat_listener_status()
wechat_get_buffered_messages(clear=true)
wechat_stop_listener()表情包工具
工具 | 说明 |
| 从聊天记录中提取表情包,生成表情包统计/列表 |
| 在表情包库中搜索 |
| 列出表情包库全部内容 |
| 手动添加表情到库(命名,用于占位符) |
| 解析文本里的 |
示例:
wechat_build_sticker_library(chat_name="张三", limit=500)
wechat_search_stickers(query="搞笑", limit=10)
wechat_parse_sticker_placeholder(text="哈哈 [sticker:狗头]")实时消息监听 CLI 工具
项目包含一个独立的命令行工具 wechat-listen,可以实时监听并显示微信新消息。
使用方法
自动检测消息目录:
wechat-listen指定消息目录:
wechat-listen --msg-dir "D:\xwechat_files\wxid_xxx\db_storage\message"设置轮询间隔:
wechat-listen --interval 0.3功能说明
进入交互模式后,实时显示新收到的消息
显示发送者、会话、消息内容和时间
按
Ctrl+C退出监听适合用于实时监控微信消息
示例输出
启动监听器...
监听器已启动,监控: D:\xwechat_files\wxid_xxx\db_storage\message
按 Ctrl+C 退出
==================================================
[16:30:15] [群] 工作群
张三: 大家好
[16:31:02] 李四
李四: 收到
常见使用场景
场景 1:把你的聊天风格“蒸馏”成系统提示词
对多个你常用的会话做
wechat_distill_skill将输出的
system_prompt放到你使用的任意 LLM/Agent 的 system prompt 中
场景 2:自动回复(需要你自己实现“发送”)
本项目只负责读数据 / 监听 / 风格蒸馏。
你可以组合:
wechat_start_listener获取新消息LLM 根据蒸馏后的风格生成回复(可带
[sticker:xxx])再用 UI 自动化/其他方式去“发送”(发送不在本项目范围内)
License
MIT
Available Tools
20 toolswechat_add_stickerB
Add a sticker to the library.
Args: name: Name for the sticker (used in [sticker:name] placeholders) md5: MD5 hash of the sticker file_path: Path to the sticker file description: Description of the sticker tags: Comma-separated tags for searching
Returns: Status message
Inputs: md5 (required), name (required), file_path (required), tags, +1 more. Returns: result
wechat_build_sticker_libraryA
Build sticker library from chat history.
Extracts sticker information including MD5, type, usage count.
Args: chat_name: Chat name to analyze limit: Maximum messages to scan copy_files: Whether to copy sticker files to output_dir output_dir: Directory to copy sticker files (if copy_files=True)
Returns: JSON with sticker library and usage patterns
Inputs: chat_name (required), limit, copy_files, output_dir. Returns: result
wechat_contactsC
Search WeChat contacts
Inputs: query, detail. Returns: result
wechat_distill_skillA
Distill personal communication style from chat history into an Agent Skills compliant SKILL.md.
Args: chat_names: Comma-separated list of chat names to analyze message_limit: Maximum messages to analyze per chat output_format: 'markdown' (Agent Skills SKILL.md) or 'json'
Returns: Agent Skills compliant skill data with YAML frontmatter, style rules, and few-shot examples
Inputs: chat_names (required), message_limit, output_format. Returns: result
wechat_favoritesC
List WeChat favorites/bookmarks
Inputs: query, msg_type. Returns: result
wechat_get_buffered_messagesA
Get buffered messages from the listener.
Args: clear: Whether to clear the buffer after reading (default True)
Returns: JSON array of buffered messages
Inputs: clear. Returns: result
wechat_historyB
Read chat history from a specific WeChat conversation
Inputs: chat_name (required), limit, msg_type. Returns: result
wechat_listener_statusA
Get the current status of the message listener.
Returns: Listener state and statistics
Inputs: no named parameters. Returns: result
wechat_list_stickersA
List all stickers in the library.
Returns: JSON object with all stickers
Inputs: no named parameters. Returns: result
wechat_membersC
List members of a WeChat group
Inputs: group_name (required). Returns: result
wechat_new_messagesA
Get new WeChat messages since last check (incremental)
Inputs: no named parameters. Returns: result
wechat_parse_sticker_placeholderA
Parse sticker placeholders from text.
Example: "Hello [sticker:dog]" -> [{"type": "text", "content": "Hello "}, {"type": "sticker", "name": "dog"}]
Args: text: Text with sticker placeholders
Returns: JSON array of parsed parts
Inputs: text (required). Returns: result
wechat_save_skillA
Distill and save skill to file as Agent Skills compliant SKILL.md.
Args: chat_names: Comma-separated list of chat names output_path: Path to save the skill file (will create SKILL.md per Agent Skills spec) message_limit: Maximum messages per chat output_format: 'markdown' (Agent Skills SKILL.md) or 'json'
Returns: Path to saved SKILL.md file or error message
Inputs: chat_names (required), output_path (required), message_limit, output_format. Returns: result
wechat_searchC
Search WeChat messages by keyword
Inputs: keyword (required), limit, chat_name. Returns: result
wechat_search_stickersB
Search sticker library by name or description.
Args: query: Search query limit: Maximum results to return
Returns: JSON array of matching stickers
Inputs: query (required), limit. Returns: result
wechat_sessionsC
List recent WeChat chat sessions/conversations
Inputs: limit. Returns: result
wechat_start_listenerA
Start listening for new WeChat messages.
The listener monitors database changes and buffers new messages. Use wechat_get_buffered_messages to retrieve them.
Args: msg_dir: WeChat message directory path (e.g., "D:\xwechat_files\wxid_xxx\msg"). If not provided, will auto-detect. interval: Polling interval in seconds (default 0.5)
Returns: Status message
Inputs: msg_dir, interval. Returns: result
wechat_statsC
Get statistics for a WeChat chat
Inputs: chat_name (required), end_time, start_time. Returns: result
wechat_stop_listenerA
Stop the message listener.
Returns: Status message
Inputs: no named parameters. Returns: result
wechat_unreadC
Show unread WeChat sessions
Inputs: limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Tools have mostly distinct purposes, with slight overlap between message retrieval tools (history, new_messages, get_buffered_messages) but descriptions clarify differences. Sticker and skill tools are well-separated.
All tools start with 'wechat_', but some follow verb_noun pattern (wechat_add_sticker) while others are noun-only (wechat_contacts, wechat_history), causing minor inconsistency.
20 tools is appropriate for a WeChat integration, covering contacts, sessions, messages, stickers, skills, and listener functionality without being overwhelming.
Missing core functionality like sending messages or modifying contacts, which are expected for a chat server. Focus is on data retrieval and analysis, leaving significant gaps.
Maintenance
Related MCP Connectors
Free WhatsApp MCP server for ChatGPT and Claude: read and search chats, every send you approve.
MCP server for AI dialogue using various LLM models via AceDataCloud
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server for WeChat PC automation, enabling message sending, voice/video calls, and AI-powered listening through Cursor or WorkBuddy.2-
- AlicenseBqualityCmaintenanceA local-first MCP server that lets agents search and summarize a user's own WeChat history, with stable pagination, bulk chat workflows, unread/event queries, and gated enrichment tools.193MIT
- AlicenseNot gradedqualityBmaintenanceMCP server providing an Agent-first, read-only interface to authorized WeChat conversations, with CLI and plugin support for Codex and Claude Code.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to query local WeChat chat data through read-only MCP tools, including sessions, messages, contacts, search, and statistics, with everything processed locally.63 PyPI6MIT