wechat-local-mcp

一个只读的本地 MCP 服务，用来把你自己的 macOS 微信聊天变成可搜索、可提取待办的上下文。

它分成两层：

1. 一次性准备层：从本机微信账号目录捕获每个数据库的 32 字节密钥，并把数据库解密成独立快照。
2. MCP 查询层：只读取快照，不向微信发消息、不修改微信数据库、不联网。

这样微信升级时，只需要替换准备层；wechat_list_chats、wechat_search_messages、wechat_find_todos 等工具不需要跟着重写。

数据位置与版本兼容

wechat_status 会动态读取当前微信版本。聊天数据库通常位于：

~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<账号>/db_storage/

较新的 macOS 微信可能为每个数据库使用独立密钥，旧版“一个 key 解所有库”的工具不能直接复用。微信升级后，数据库结构或密钥派生方式仍可能变化。工具不会覆盖 /Applications/WeChat.app，也不会对日常微信做重签名。

安全与隐私

• 仓库不包含真实密钥、微信数据库、聊天导出、账号目录或本机虚拟环境。
• MCP 服务自身不要求网络访问，只读取本机解密快照。
• 当 MCP 客户端把查询结果交给模型分析时，被选中的聊天内容会进入该客户端的模型上下文；请按所用客户端的隐私策略判断是否使用。
• 密钥捕获脚本只应当用于你有权访问的本机微信账号。
• keys.json 和明文快照默认保存在项目目录之外的用户配置目录中，并限制为仅当前系统账户可读；不要提交或分享它们。

安装

在本目录执行：

uv sync --extra keys --extra ui --extra test --python /opt/homebrew/bin/python3.12

查看状态：

uv run --python /opt/homebrew/bin/python3.12 wechat-local-sync status

一次性准备密钥

如果你已有可用的 keys.json，放到：

~/.config/wechat-local-mcp/keys.json

格式是数据库相对路径（或文件名）到 64 位十六进制密钥的映射，例如：

{
  "contact/contact.db": "REPLACE_WITH_64_HEX_CHARACTERS",
  "message/message_0.db": "REPLACE_WITH_64_HEX_CHARACTERS"
}

如果没有 keys 文件，项目附带一个不改日常微信安装包的 Frida 辅助脚本。先安装可选依赖：

uv sync --extra keys --python /opt/homebrew/bin/python3.12

直接附加日常微信在部分 macOS 版本上会被系统拒绝。如果本机允许附加，可以退出并重新打开微信后运行：

uv run --python /opt/homebrew/bin/python3.12 python scripts/capture_keys.py \
  --pid "$(pgrep -x WeChat | head -1)" \
  --db-dir "$HOME/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<账号>/db_storage"

这只把捕获到的派生 key 合并写入 ~/.config/wechat-local-mcp/keys.json，不会清除之前已捕获的有效 key。如果 macOS 报 task_for_pid 或权限错误，请使用专用副本：

zsh scripts/prepare_capture_copy.sh

退出日常微信后，用 --spawn "$HOME/Applications/WeChatKeyCapture.app/Contents/MacOS/WeChat" 运行捕获脚本。脚本会在微信启动时安装只读派生函数观察器；当前版本通常无需再次扫码。脚本不会替你修改系统设置，也不会对日常使用的 /Applications/WeChat.app 重签名。

密钥捕获是一次性环境准备，当前微信版本或下次升级后可能需要重新做。不要把 keys.json、明文数据库或聊天导出文件提交到 Git。

解密本地快照

建议先完全退出微信，再执行：

uv run --python /opt/homebrew/bin/python3.12 wechat-local-sync sync

默认输出到：

~/Library/Application Support/wechat-local-vault/decrypted/current/

也可以通过环境变量覆盖：

export WECHAT_CONTAINER_DIR="$HOME/Library/Containers/com.tencent.xinWeChat/Data/Documents"
export WECHAT_DECRYPTED_DIR="$HOME/Library/Application Support/wechat-local-vault/decrypted/current"
export WECHAT_KEYS_FILE="$HOME/.config/wechat-local-mcp/keys.json"

配置 MCP

以 stdio 方式添加到支持 MCP 的客户端：

{
  "mcpServers": {
    "wechat-local": {
      "command": "/绝对路径/outputs/wechat-local-mcp/.venv/bin/wechat-local-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

或直接运行：

uv run --python /opt/homebrew/bin/python3.12 wechat-local-mcp --transport stdio

Codex CLI 可直接注册：

codex mcp add wechat-local -- \
  "/绝对路径/outputs/wechat-local-mcp/.venv/bin/wechat-local-mcp" \
  --transport stdio

可用工具

• wechat_status：检查微信版本、数据库、密钥与快照状态。
• wechat_sync：按 keys.json 解密数据库到独立快照目录。
• wechat_list_chats：列出联系人和群聊，支持分页。
• wechat_read_chat：按昵称、备注、群名或微信 ID 读取消息。
• wechat_search_messages：按关键词、聊天和时间范围搜索消息。
• wechat_recent_messages：汇总最近消息。
• wechat_find_todos：用可解释的中英文行动项启发式找待办候选。
• wechat_chat_summary：返回参与者统计和待办候选，供模型进一步总结。
• wechat_ui_diagnose：诊断屏幕录制/OCR 只读兜底。
• wechat_list_recent_chats：数据库快照不可用时读取当前窗口可见会话。
• wechat_read_chat_ui：数据库快照不可用时用本机 OCR 读取聊天。
• wechat_find_todos_ui：对 OCR 结果做待办候选提取。

所有查询工具都是只读的；wechat_find_todos 只返回候选，不会替你创建任务、发消息或修改微信。

OCR 兜底需要：

uv sync --extra ui --python /opt/homebrew/bin/python3.12

并在系统设置中允许运行 MCP 的终端使用“屏幕与系统音频录制”。OCR 是当前屏幕的近似读取，长期历史、精确 sender 和全文搜索仍以数据库快照后端为准。

验证

uv run --python /opt/homebrew/bin/python3.12 pytest
uv run --python /opt/homebrew/bin/python3.12 wechat-local-sync status

若没有明文快照，MCP 会返回下一步提示，不会把加密数据库误当成可读内容。

许可证与声明

本项目采用 MIT License。

本项目是社区开发的非官方工具，与腾讯或微信团队无隶属或背书关系。“微信”和“WeChat”及相关标识属于其各自权利人。