Skip to main content
Glama
wechat-local

wechat-local

by nanlis

wechat-ai-history

把本机微信 4.x 的聊天记录,变成 AI 可以直接调用的能力。

密钥提取 → 数据库解密 → MCP server → Agent Skill,全链路本地只读。

Windows Python License


这是什么

一句话:在你的电脑上,给 AI 装上一双能读微信的眼睛。

以前想把群里的一段记录给 AI,你得截图、复制、粘贴,格式全乱、上下文丢一半。 现在一句话就行,而且 AI 拿到的是结构化的、带时间戳和发送者的原文。

能力

说明

列会话 / 找群

列出全部会话和群,直接给群名和 wxid

读某个群

支持全部历史,不只是最近 7 天

全文搜索

跨多个消息分片库检索,量级不影响速度

摘要 / 系统事件

撤回、转账、拍一拍、进群退群等独立入口

这东西是给谁用的?

能力是通用的,数据是你自己的。 三层作用域说清楚:

层

换账号 / 换电脑还成立吗

说明

技术内核(提 key、解密、zstd、XML 解析、搜索、MCP、Skill)

✅ 完全成立

与「谁的微信」无关。任何 Windows 机器 + 任何微信 4.x 账号,跑同一套流程

密钥

🔁 一号一钥匙

raw key 按账号派生,一把 key 只开得了它所属的账号。换账号就重跑一次「提 key → 解密」,代码一行不改

明文库 / 导出产物

❌ 不迁移

只属于这台机器这个账号。已全部 .gitignore,从未进仓库

换账号不用改代码:密钥自己会认账号。decrypt_all.py 会拿 key 逐个探测数据根下的所有账号目录, 只解开能打开的那一个——不会像「按文件修改时间猜活跃账号」那样在多账号机器上选错。 想锁定某个账号:--account <目录名或wxid>,或设环境变量 WECHAT_ACCOUNT。

仓库里不含任何真实账号 id、群 id、路径或聊天内容。已用测试锁死 (tests/test_account_portability.py):源码里出现具体 wxid 或机器专属路径,测试直接失败。

Related MCP server: wxq

为什么现成工具都不行

方案

卡在哪

微信官方

没有导出接口,备份是加密的、换机就废

常规「内存扫密钥」

微信 4.x 把 OpenSSL 全静态链接进 DLL,扫 8773 个导出符号没有 PBKDF2/HMAC/sqlite3_key 可钩

WeFlow

做得很全,但 README 明说「依赖自定义的原生解密组件,需自行设计」——这块留空了

wx-cli

只认 ~/Documents/xwechat_files,认不出自定义数据路径

本仓库填的就是那块空。

快速开始(全新 Windows 电脑)

git clone https://github.com/nanlis/wechat-ai-history.git
cd wechat-ai-history
bash install.sh

安装脚本会自动完成:探测 Python → 探测微信 → 探测数据目录 → 建 venv 装依赖 → 创建目录联接 → 注册 MCP server → 安装 Skill 到各运行时。

换一台新电脑意味着什么

这套东西的形态是仓库 + 本地能力,不是打包好的 exe。所以「换机」这件事 要拆成两块看:

要带走的东西

换机后怎么办

说明

代码与知识(解析器、MCP、Skill、测试)

git clone 一条命令

全部在 GitHub 上,零成本带走

密钥(能解密数据库的那把钥匙)

必须重新提取

密钥与设备绑定,不是文件拷贝能解决的

明文数据库(你那 115 万条聊天记录)

重新解密生成

一次操作,几分钟

AI 客户端配置(MCP + Skill)

install.sh 自动重写

指向新机器的真实路径

也就是说:换电脑要重跑一次「提密钥 → 解密」,但不用重写任何一行代码。

新机器上的完整流程:

git clone https://github.com/nanlis/wechat-ai-history.git
cd wechat-ai-history
bash install.sh            # 自动探测,装依赖、注册 MCP 和 Skill
# 启动微信并登录一次
bash scripts/windows/refresh_key.sh   # 提密钥 + 解密全部库

装完之后在这台新电脑上,AI 拿到的仍然是完整能力: 读群、翻历史、全文搜索、导出、看系统事件 —— 数据是这台电脑上这个微信账号的。

关于「不用再装一遍」

install.sh 是幂等的,可以重跑。它会:

  • 探测 Python / 微信 / 数据目录,探测不到才问你

  • 已存在的 venv 跳过,已有的联接识别为「就绪」

  • 旧版本留下的空目录自动备份后重建(不会卡住)

  • 用目录联接把整个仓库挂成 Skill,保证 references/ 手册页和 scripts/ 运行时脚本都能被 AI 读到(只复制一个 SKILL.md 是不够的)

装完先跑一次只读体检:

.venv/Scripts/python.exe scripts/common/doctor.py --json

它会告诉你:密钥在不在、库能不能读、MCP 有没有注册、Skill 有没有装对。

前置条件

项

要求

操作系统

Windows 10+ x64

微信

4.0 及以上(4.1.x 已验证)

Python

3.11+(frida 17 要求;3.13 已验证)

终端

Git Bash 以管理员身份运行(读微信进程内存需要)

磁盘

≥3 GB(明文库约为主库的 1.3 倍)

网络

仅安装依赖与克隆仓库时需要,运行期全程离线

关于数据目录

脚本会自动探测以下常见位置,探测不到会交互式询问:

C:\Users\<你>\Documents\xwechat_files     # 微信默认
D:\WeChatData\xwechat_files               # 数据目录被挪到别的盘
E:\Chat\xwechat_files

也可以显式指定(Windows 或 Git Bash 两种写法都接受):

bash install.sh "D:\WeChatData\xwechat_files"
bash install.sh /d/WeChatData/xwechat_files

然后三步

# 1. 从桌面双击启动微信并登录
#    (登录会重新派生数据库密钥 —— 这是提取密钥的唯一可靠时机)

# 2. 提取密钥 + 解密全部数据库
bash scripts/windows/refresh_key.sh

# 3. 在 WorkBuddy / Claude Code 里点一次「信任」wechat-local
#    (连接器管理页 → 右上角自定义连接器入口)

之后直接说:

「把 XX 群的记录发给我」
「搜一下我微信里关于 XX 的聊天」

架构

AI 客户端          WorkBuddy · Claude Code · Codex
    ↓
Skill              skill/SKILL.md —— 教 AI 何时调、怎么调、有哪些坑
    ↓
MCP Server         server.py —— 7 个工具,stdio,本地
    ↓
内核               scripts/windows/ —— 提密 → 解密 → 查询
    ↓
数据               微信本地数据目录(SQLCipher 4 加密)

三层缺一不可:只有 Skill,AI 每次要现拼命令;只有 MCP,AI 不知道工具存在;只有内核,那只是脚本,不是能力。

核心突破:怎么拿到密钥

微信 4.x 把 OpenSSL 全部静态链接进 DLL,没有任何可钩的导出符号。 最终方案是钩 SHA-512 压缩函数,从 HMAC 内层的 ipad 块还原明文 key:

HMAC 内层:ipad = key ⊕ 0x36
→ 抓到 ipad,XOR 回 0x36 即得明文 key

三个必须同时满足的条件(换版本会踩的坑):

  1. 钩全部模块 —— 只钩 Weixin.dll 会抓到 TLS 的 HMAC 假货

  2. 候选落盘再离线验证 —— 在线验证会漏,4 个 TLS 假货就是这么混进来的

  3. 微信登录那一刻 —— SQLCipher 只在首次打开某个库时派生密钥

SQLCipher 4 参数

enc  = PBKDF2-HMAC-SHA512(raw_key, db_salt, 256000, 32)   # 每库独立
mack = PBKDF2-HMAC-SHA512(enc, db_salt ^ 0x3A, 2, 32)
AES-256-CBC · page 4096 · reserve 80

工具清单

脚本

作用

scripts/windows/hook_raw_key_broad.py

钩全部模块,捕获并落盘密钥候选

scripts/windows/decrypt_stream.py

流式解密(676MB 主库 8 秒,避免 MemoryError)

scripts/windows/decrypt_all.py

全量解密

scripts/windows/wxread.py

列会话 / 读群 / 搜索 / 导出 txt

scripts/windows/refresh_key.sh

一键提密钥 + 重解密

scripts/windows/find_k1.py

内存中定位单库的派生密钥

scripts/windows/find_ctx.py

按 kdf_iter=256000 常量定位 SQLCipher ctx

scripts/windows/dump_exports.py

扫描 DLL 导出符号

server.py

MCP server(7 工具)

install.sh

全新电脑一键安装

已验证的规模

下表是某一个账号的实测值(一个长期使用、群聊较多的微信号)。 它是能力上限的证明,不是你的预期值——绝大多数账号远小于这个数。 新号可能只有几千条消息,工具行为完全一样,耗时也几乎一样。

项

数值

解密数据库

21 个 / 1.3 GB 明文

消息总数

1,157,006 条

会话

7,521 个(含 179 个群)

群成员

26,659 人

integrity_check

ok

测试环境

Windows · 微信 4.1.15.56

规模由你的聊天记录量决定,不由工具决定。 微信把每个会话拆成独立的 Msg_<md5(session_uid)> 分表,所以:

  • 会话多 → 分表多,但每个分表独立查询,不互相拖慢

  • 消息少 → 搜索照样秒回,不会因为"数据太少"而失灵

  • 已有极端场景验证:只保留 1 个会话、3 条消息时,列会话 / 搜索 / 统计 全部正常返回,不报错、不空转

所以拿这个方案的人,不用先攒够 100 万条。新号一样能用。

已知限制

  • 富媒体正文解不开:图片/表情/视频/语音的正文由 WCDB 单独加密,工具只能标注类型。 文本消息 100% 可读。仓库内有 export_media.py / voice_decode.py 可进一步接驳。

  • 密钥随微信登录/升级失效:跑 refresh_key.sh 重新提取。

  • 微信 4.x 不再填充 SessionTable.type:群靠 @chatroom 后缀识别。

  • 需要管理员权限读取微信进程内存。

安全边界

  • 密钥(key_windows.txt)等同微信账号的钥匙,绝不入库、不外传、不打印到对话

  • 解密后的明文库涉及群友隐私,全程本机,零联网

  • .gitignore 已强制排除密钥、decrypted/、*.db 及各类中间产物

  • 只操作用户本机、用户有权访问的数据

请负责任地使用本工具,遵守相关法律法规。

开发者

.venv/Scripts/pip install -r requirements-dev.txt   # 运行时依赖 + pytest
.venv/Scripts/python.exe -m pytest -q

测试全部使用合成数据库,不需要微信运行、不需要真实密钥, 在一台刚 clone 下来的干净机器上也能全绿。

仓库自带脱敏审计工具,会扫描工作区 + 全部 git 历史 + 提交信息:

.venv/Scripts/python.exe scripts/common/scrub_audit.py

CI 说明

上游仓库自带 GitHub Actions 配置(跑 pytest + 校验 MCP 工具数为 7)。 由于推送用的 OAuth token 缺少 workflow scope,配置文件暂存于 .github-ci/workflows/tests.yml。补齐 scope 后一条命令恢复:

gh auth refresh -h github.com -s workflow
git mv .github-ci/workflows .github/workflows
git push

致谢与出处

本仓库基于 tzwkb/wechat-decrypt(MIT License, Copyright (c) 2026 cocofeng)演进而来。原仓库提供了跨平台解密框架骨架, 本仓库在 Windows 微信 4.x 上的关键突破为:

  • SHA-512 压缩函数挂钩方案与全模块覆盖策略

  • 大库流式解密(decrypt_stream.py)

  • 跨分片搜索、MCP server 接入、Agent Skill 封装

  • 全新电脑一键安装流程

上游原始说明见 README.upstream.md / README_ZH.upstream.md, 技术细节见 docs/windows-4.x-key-extraction.md 与 docs/architecture.md。

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides AI clients read-only access to WeChat chat history by extracting and decrypting the local Mac database, enabling search, summary, and analysis of messages.
      1
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 PyPI
      6
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables authorized AI clients to search locally stored WeChat conversations, media, and attachments, retrieve original-message context, and cite evidence through a local stdio MCP interface.
      AGPL 3.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to list permitted WeChat group chats, fetch cleaned message histories by cursor or time window, search messages with context, and export decrypted group media through a read-only offline MCP stdio interface.
      4
      MIT