wechat-local
Reads the local WeChat 4.x chat history database on the user's Windows machine, providing tools to list sessions and groups (by name and wxid), read the full message history of a group with timestamps and senders, perform full-text search across message shard databases, and access summaries and system events such as recalls, transfers, pats, and group joins/leaves.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
wechat-ai-history
把本机微信 4.x 的聊天记录,变成 AI 可以直接调用的能力。
密钥提取 → 数据库解密 → MCP server → Agent Skill,全链路本地只读。
这是什么
一句话:在你的电脑上,给 AI 装上一双能读微信的眼睛。
以前想把群里的一段记录给 AI,你得截图、复制、粘贴,格式全乱、上下文丢一半。 现在一句话就行,而且 AI 拿到的是结构化的、带时间戳和发送者的原文。
能力 | 说明 |
列会话 / 找群 | 列出全部会话和群,直接给群名和 wxid |
读某个群 | 支持全部历史,不只是最近 7 天 |
全文搜索 | 跨多个消息分片库检索,量级不影响速度 |
摘要 / 系统事件 | 撤回、转账、拍一拍、进群退群等独立入口 |
这东西是给谁用的?
能力是通用的,数据是你自己的。 三层作用域说清楚:
层 | 换账号 / 换电脑还成立吗 | 说明 |
技术内核(提 key、解密、zstd、XML 解析、搜索、MCP、Skill) | ✅ 完全成立 | 与「谁的微信」无关。任何 Windows 机器 + 任何微信 4.x 账号,跑同一套流程 |
密钥 | 🔁 一号一钥匙 | raw key 按账号派生,一把 key 只开得了它所属的账号。换账号就重跑一次「提 key → 解密」,代码一行不改 |
明文库 / 导出产物 | ❌ 不迁移 | 只属于这台机器这个账号。已全部 |
换账号不用改代码:密钥自己会认账号。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 可钩 |
做得很全,但 README 明说「依赖自定义的原生解密组件,需自行设计」——这块留空了 | |
wx-cli | 只认 |
本仓库填的就是那块空。
快速开始(全新 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、测试) |
| 全部在 GitHub 上,零成本带走 |
密钥(能解密数据库的那把钥匙) | 必须重新提取 | 密钥与设备绑定,不是文件拷贝能解决的 |
明文数据库(你那 115 万条聊天记录) | 重新解密生成 | 一次操作,几分钟 |
AI 客户端配置(MCP + Skill) |
| 指向新机器的真实路径 |
也就是说:换电脑要重跑一次「提密钥 → 解密」,但不用重写任何一行代码。
新机器上的完整流程:
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三个必须同时满足的条件(换版本会踩的坑):
钩全部模块 —— 只钩
Weixin.dll会抓到 TLS 的 HMAC 假货候选落盘再离线验证 —— 在线验证会漏,4 个 TLS 假货就是这么混进来的
微信登录那一刻 —— 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工具清单
脚本 | 作用 |
| 钩全部模块,捕获并落盘密钥候选 |
| 流式解密(676MB 主库 8 秒,避免 MemoryError) |
| 全量解密 |
| 列会话 / 读群 / 搜索 / 导出 txt |
| 一键提密钥 + 重解密 |
| 内存中定位单库的派生密钥 |
| 按 |
| 扫描 DLL 导出符号 |
| MCP server(7 工具) |
| 全新电脑一键安装 |
已验证的规模
下表是某一个账号的实测值(一个长期使用、群聊较多的微信号)。 它是能力上限的证明,不是你的预期值——绝大多数账号远小于这个数。 新号可能只有几千条消息,工具行为完全一样,耗时也几乎一样。
项 | 数值 |
解密数据库 | 21 个 / 1.3 GB 明文 |
消息总数 | 1,157,006 条 |
会话 | 7,521 个(含 179 个群) |
群成员 | 26,659 人 |
| 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.pyCI 说明
上游仓库自带 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
A paid remote MCP for AI SDK data query MCP, built to return verdicts, receipts, usage logs, and aud
Read-only WhatsApp MCP for your AI agent: it reads the chats you choose. Try the public demo.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides 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-
- 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
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseAqualityCmaintenanceEnables 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.4MIT