微信本地聊天 MCP

让 Claude Code 直接读你电脑上自己的微信聊天记录。 只在本机读写，不联网、不上传、不注入微信进程。

一图看懂

flowchart LR
    subgraph WX["微信 4.x（必须正在运行）"]
        M["Weixin.exe 内存<br/>数据库密钥"]
        DB[("db_storage/*.db<br/>SQLCipher 加密")]
        ATT["msg/attach、msg/file<br/>图片 / 文件原件"]
    end

    subgraph TOOL["wechat-local-mcp（只在你本机）"]
        K["wxcore<br/>只读扫描 + HMAC 验真"]
        D[("明文 SQLite<br/>%LOCALAPPDATA%\\wechat-mcp")]
        Q["wxquery<br/>会话索引 / 搜索 / 渲染"]
    end

    M -. "PROCESS_VM_READ" .-> K
    K -->|解密| D
    DB --> D
    ATT --> Q
    D --> Q
    Q --> C["Claude Code"]

一句话：微信把库加密了，密钥只在运行中的微信进程内存里；本工具把密钥读出来、把库解开、再通过 MCP 协议交给 Claude。

Related MCP server: wxq

效果

在 Claude Code 里说「看看我和某某最近聊了什么」，返回长这样：

=== 某某（wxid_xxxxxxxxxxxx，总计 16464 条）最近 12 条 ===
2026-11-10 14:13  我: 我到学校了
2026-11-10 14:13  某某: 好棒
2026-11-10 14:21  某某: （48.7秒）这个方案我看了，前面没问题
2026-11-09 23:52  我: [图片] C:\Users\you\AppData\Local\wechat-mcp\images\a1b2c3d4_9f8e.jpg
2026-11-09 22:40  我: [文件] 需求文档.docx（1.2 MB）
                       本地：D:\xwechat_files\...\msg\file\2026-11\需求文档.docx
2026-11-09 20:00  某某: [集录] 聊天记录，共 12 条
                        甲: 这个先放一放
                        乙: 好
2026-11-09 19:12  我: [引用] 收到
                        原话（某某）：周五之前给我
2026-11-09 09:49  某某: 通话 00:40
2026-11-08 18:30  系统: 你撤回了一条消息

能做什么

read_chat 的 who 参数支持备注名 / 昵称 / 群名 / wxid，并且支持片段模糊匹配；匹配到多个时会列出候选让你选。

voice_transcripts 是给「和别的微信索引搭配用」准备的：别人把语音统一存成 [语音]， 这个工具只挑语音出来、只解析 packed_info_data，比重读整个会话便宜得多。 返回里每条都带 epoch（秒级时间戳），可以直接和别的库的 create_time 对上。

和现成的比，这个有什么用

先说结论：如果你只是想要一个能用的产品，本项目不是最优选。GitHub 上已经有做得更全的同类项目。

同类项目现状

那为什么还留着这个

① 它处理语音，别人不处理

im-mcp 的 29 个工具和整篇功能列表里，检索「语音 / voice / 转写 / SILK / audio」全部 0 命中。 而语音在微信里占比极高——本项目实测一个账号 23,718 条语音。不处理等于整段对话是空的。

本项目从 packed_info_data 的 protobuf（字段 5 → 2）里取出微信自己做的转写配在消息里， 秒数从 voicelength 取。取不到时明确告诉你「没有转写」，而不是丢一个 [语音] 就完事。

证据等级：检索过对方 README，也读过对方 adapters/media.py、parser.py、tools/key_tool.py 的源码。 源码里「语音」只作为消息类型标签出现（34: "语音"、17: "实时语音"）， 没有 packed_info_data、没有转写提取、没有音频解码。这一条是可以核实的。

② 小到能读完

7 个文件 1,739 行 Python，没有框架、没有构建步骤、没有子模块。 想搞明白「微信的库到底是怎么加密的、Claude 是怎么拿到聊天记录的」，从这个仓库读进去比读一个大项目快得多。

③ 在 4.2.0.9 上跑通过

实测环境是微信 4.2.0.9，密钥掩码沿用 4.1.15.56 那一版，24 个库全部 HMAC 验真通过。

这一条要说清楚，别夸大：读过 im-mcp 的 key_tool.py，它扫的是 com.Tencent.WCDB.Config.Cipher 这个特征串，再拿候选密钥去和库文件的 salt 做 HMAC 比对—— 不是写死内存偏移，所以版本号差一位大概率不影响，最坏情况是「扫到 0 个密钥」而不是「解出错数据」。 也就是说，im-mcp 很可能在 4.2.0.9 上也能用，只是对方没声明测过。

它明显不如别人的地方

一句话：本项目是一个「小而完整、能读懂、把语音也解了」的样本；要功能全，用 im-mcp。

推荐：两个一起装

两个服务可以同时注册到 Claude Code，互不冲突：

claude mcp add wechat-im --scope user -- "<im-mcp 的 wechat-mcp.exe>"

# 关键一行：让本工具直接读 im-mcp 解密出来的那份明文，盘上只留一份
claude mcp add wechat-local --scope user \
  -e "WECHAT_DEC_DIR=%USERPROFILE%\.wechat_mcp\decrypted" \
  -- "<python>" "<本仓库>/server.py"

分工是：日常查询、搜索、头像、收藏走 wechat-im；碰到语音再调 wechat-local 的 voice_transcripts 补一次。 两边都按秒级时间戳对得上，合并时不会有歧义。

用了 WECHAT_DEC_DIR 以后，本工具的 refresh_data 就不用再调了——数据的新鲜度交给 im-mcp 的 sync_wechat_database，本工具只负责读。refresh_data / clear_cache 在这种模式下会明确拒绝（见下节）。

消息里那些非文字的东西

语音：只能拿微信转过的

微信 4.x 不在本地保存语音音频——只在消息里留一条「取货单」：

<voicemsg voiceformat="4" voicelength="23340" length="41557"
          aeskey="1ac5366da6b055a8657fceaa74eb6e1e" />

音频本体按需从腾讯服务器取，播放时在内存里解码、完了就扔（cache\...\VoiceTemp 目录是空的）。 所以对方没触发过转文字的语音，本工具只能告诉你它有多少秒。

想让它有字，办法只有一个：在微信里打开「语音自动转文字」，或在单条语音上长按选「转文字」。 微信转完会把结果写回 packed_info_data，本工具下一次就能读到。

实测数据：某账号全库 23,718 条语音，微信已转写的只有 442 条（2%）。 这个开关不开，绝大部分语音对 Claude 来说是空的。

图片：要单独取一次密钥

微信 4.x 的图片存在 msg\attach\<会话hash>\<年-月>\Img\<md5>.dat，V2 格式：

[6B 魔数 07 08 56 32 08 07] [4B AES段长] [4B XOR段长] [1B 填充]
[AES-128-ECB 段] [明文段] [XOR 段]

• XOR 键能从文件自己推（JPEG 以 FF D9 结尾），实测固定是 0xF3。

• AES 键没有固定值，是 16 个 ASCII 字符，只在微信解码图片那一瞬间进内存， 空闲时把整个进程内存扫一遍也扫不到。

所以取密钥要「配合时机」：

# 1. 在微信里点开两三张图片（看到大图就关掉）
# 2. 立刻运行：
python find_image_key.py

# 抓不到就开监视模式，一边点图一边等它抓：
python find_image_key.py --watch

# 之后验证存下来的密钥还能不能用：
python find_image_key.py --check

密钥存在 %LOCALAPPDATA%\wechat-mcp\imgkey.txt。微信重启后可能失效，失效了重跑一次即可。

消息和 .dat 怎么对上？ 磁盘文件名不是消息里的 md5（那是另一套，按 md5 一个都找不到）。 真正的对应关系是明文长度：

消息 XML 的 length  =  原图解出来多少字节
.dat 的明文长       =  AES段 + 明文段 + XOR段 − PKCS7填充

两边一比就配上了。实测一个会话：原图 23/25 命中，剩下 2 条用 cdnthumblength 对 _t.dat 缩略图 25/25 命中。

格式推断不用等密钥就能验——造一个假 .dat 再解回来逐字节比对：

python find_image_key.py --selftest

文件：只给已经下载到本机的

消息里只有文件名和大小；原件在 msg\file\<年-月>\ 下，按文件名索引，同名多份时用大小和修改时间挑。 没下载到这台电脑的文件，只能告诉你「本地没有」。

快速开始

1. 环境要求

• Windows 10 / 11（要读另一个进程的内存，其他系统不支持）

• 微信 4.x 正在运行（实测 4.2.0.9）

• Python 3.10+

2. 装依赖

pip install -r requirements.txt

3. 解密一次

python refresh.py

正常会打印：

微信根 : D:\xwechat_files
账号   : D:\xwechat_files\wxid_xxx_7f3a（wxid_xxx）
库目录 : D:\xwechat_files\wxid_xxx_7f3a\db_storage
输出   : C:\Users\you\AppData\Local\wechat-mcp\decrypted

解密 5 个库，用时 20.8s
  [OK] contact\contact.db                 5.12 MB
  [OK] message\message_0.db             103.96 MB
  ...

4. 注册到 Claude Code

claude mcp add wechat-local --scope user -- python "<本目录绝对路径>\server.py"

重开一个 Claude Code 会话就能用了。

5. 自检

python selftest.py            # 真的连一次服务，把每个工具各调一遍
python selftest.py 某某       # 指定用哪个会话测

配置（都有默认值，一般不用设）

WECHAT_DEC_DIR 指到本工具目录以外时，读到的库按「只读」处理。 典型用法是复用别的工具解出来的明文（比如 im-mcp 的 ~\.wechat_mcp\decrypted）， 这样盘上只留一份、也不用再解一次。这种情况下 refresh_data 和 clear_cache 会直接拒绝执行并说明原因——绝不删别人的产物。

工作原理

微信把 SQLCipher 的密钥放在 Weixin.exe 的内存里，外面套了一层固定 32 字节的异或掩码：

1. 在进程内存里搜字符串 com.Tencent.WCDB.Config.Cipher

2. 顺着这个 std::string 节点的数据指针，找到它的配置对象

3. 配置对象 +0x88 处是一个「缓冲区描述符」（指针 + 长度）

4. 把这段字节和固定掩码逐字节异或，还原出 x'<32字节密钥><16字节盐>' 字面量

整个过程只读（PROCESS_VM_READ），不写微信内存、不注入 DLL。

不靠猜。每把候选密钥都拿去验第 1 页的 HMAC：

mac_key = PBKDF2-HMAC-SHA512(enc_key, salt ^ 0x3A, 迭代 2 次, 32 字节)
HMAC-SHA512(mac_key, 第1页密文 + 页码) == 第1页尾部的 64 字节 ?

验不过的一律丢掉。实测某账号 24/24 个库全部验真。

每页 4096 字节，保留区 80 字节：

第 1 页：[16B 盐][4000B 密文][16B IV][48B HMAC][16B 填充]
其余页：[        4000B 密文][16B IV][48B HMAC][16B 填充]

逐页 AES-256-CBC 解密，第 1 页把前 16 字节换成 SQLite format 3\0， 解完再跑一次 PRAGMA integrity_check，不通过就报错。

local_type 是个 64 位整数，高 32 位存来源编号，低 32 位才是消息类型：

141733920817 & 0xFFFFFFFF = 49   → 卡片消息

不掩码的话，卡片、引用、集录全会被认成「未知类型」。

群消息正文开头是 wxid_xxx:\n真正内容，前缀是发送者的 wxid。 但更可靠的是 real_sender_id → Name2Id.rowid → user_name，再经 contact.db 换成备注名。 Name2Id 里有些行的 user_name 是空串，这时才退回用正文前缀。

隐私与安全

这一节请认真看。

本工具做了什么

• ✅ 只读打开微信进程内存，不写、不注入、不改微信的任何状态

• ✅ 所有数据只在本机，不联网、不上传、不写日志到外部

• ✅ 解密产物的唯一判据是 HMAC 验真，不会把错钥匙解出来的垃圾当数据

你需要知道的

• ⚠️ 解密产物是明文，默认在 %LOCALAPPDATA%\wechat-mcp\decrypted\（约 200 MB）。 任何能读你用户目录的程序都能读到它。用完可以 python refresh.py --purge 清掉， 或让 Claude 调用 clear_cache。

• ⚠️ 内容进了对话就等于出去了。 本工具本身不联网，但 Claude 读到的聊天内容会随对话 发给模型服务端。删掉本地缓存不等于内容没离开过这台电脑。

• ⚠️ 别把这个仓库连同 %LOCALAPPDATA%\wechat-mcp\ 一起同步到网盘或公共机器。

已知限制

排错

• 微信没开，或者开了但立刻退出了

• 微信以管理员身份运行，而本工具不是 → 两边权限要一致（都用普通权限，或都用管理员）

微信升级后内存掩码变了。wxcore.py 里的 MASK 需要重新找。

让它调用 refresh_data，或自己跑一次 python refresh.py（约 10 秒）。 微信必须正在运行——密钥只在内存里。

先 python find_image_key.py --check 验证存的密钥， 不通就 python find_image_key.py --watch，然后去微信里点几张图。

微信自己没转过这条。去微信设置里打开「语音自动转文字」。

目录结构

wechat-local-mcp/
├── server.py           MCP 服务入口（Claude Code 启动时自动拉起）
├── wxcore.py           找目录 / 内存取密钥 / 逐页解密
├── wxquery.py          通讯录映射 / 会话索引 / 搜索 / 富媒体渲染
├── wxmedia.py          语音转写 / 文件索引 / 集录解析 / .dat 解密
├── find_image_key.py   从微信内存取图片 AES 密钥
├── refresh.py          命令行手动刷新（--purge 清缓存）
├── selftest.py         自检：真连一次 MCP 服务
├── requirements.txt
└── LICENSE

运行期产物（不在仓库里，默认在 %LOCALAPPDATA%\wechat-mcp）：

decrypted/    解密后的明文 SQLite（约 200 MB）
images/       解出来的图片
index.json    会话索引缓存
imgkey.txt    图片密钥

免责声明

本项目仅供读取自己账号在本机的聊天记录，用于个人数据整理与自动化和学习研究。

• 请勿用于读取他人设备、绕过他人授权或任何未经同意的场景。

• 微信的用户协议可能不鼓励此类本地数据访问，使用前请自行了解并承担相应风险。

• 作者不对因使用本工具造成的任何数据丢失、账号异常或法律后果负责。

MIT License © 2026 Lyric679