wechat-mcp-server

一个用于读取本机微信数据的 MCP Server：让 Claude Code 等 AI 助手可以通过 MCP 工具读取聊天记录/会话/联系人/收藏等。

功能特性

• 查询微信聊天记录、联系人、会话列表、收藏等
• Skill 蒸馏：从聊天记录提取个人沟通风格（统计 + Few-shot + 可生成系统提示词）
• 消息监听：近实时获取新消息（轮询会话数据库）
• 表情包管理：解析表情消息、构建表情包库，并支持解析 [sticker:xxx] 占位符

安装

# 克隆并安装
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-mcp

Windows 下推荐使用 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_mcp

Windows 下加 SSE 参数：

python -m wechat_cli_mcp --sse

工具列表（MCP Tools）

基础查询工具

工具	说明
wechat_sessions	列出最近聊天会话
wechat_history	读取指定会话的聊天记录
wechat_search	按关键词搜索消息
wechat_contacts	搜索联系人
wechat_unread	未读会话
wechat_new_messages	增量获取新消息（自上次检查之后）
wechat_members	群成员列表
wechat_stats	会话统计
wechat_favorites	收藏/书签

Skill 蒸馏工具

工具	说明
wechat_distill_skill	从聊天记录蒸馏个人沟通风格（返回 JSON 或 Markdown）
wechat_save_skill	蒸馏并保存到文件（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	启动监听（近实时）
wechat_stop_listener	停止监听
wechat_listener_status	查看监听状态
wechat_get_buffered_messages	获取监听缓冲的新消息

说明：监听器会轮询会话数据库的最新时间戳来发现新消息，并将新消息缓冲到内存中供工具读取。

示例：

wechat_start_listener(interval=0.5)
wechat_listener_status()
wechat_get_buffered_messages(clear=true)
wechat_stop_listener()

表情包工具

工具	说明
wechat_build_sticker_library	从聊天记录中提取表情包，生成表情包统计/列表
wechat_search_stickers	在表情包库中搜索
wechat_list_stickers	列出表情包库全部内容
wechat_add_sticker	手动添加表情到库（命名，用于占位符）
wechat_parse_sticker_placeholder	解析文本里的 [sticker:xxx] 占位符

示例：

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