WeChat Local Reader

本地读取 macOS 微信已同步的群聊、私聊和普通文件附件，提供增量监听、持久通知队列、JSON 命令行、Python API 和 stdio MCP 接口。

使用前提：你已具备自己微信数据库的可用密钥。 本项目负责读取和监听，不包含取钥、进程注入、修改微信签名或发送消息。无需操作微信窗口。微信升级、数据库结构或加密方式变化时，需要重新验证兼容性。

功能

• 精确匹配群名或联系人备注，并通过 allowed_chats 限定可读取范围；同名会话停止查询。

• 查询时间区间、分页、文本、引用和链接摘要；普通附件输出 available / not_downloaded。

• 从本机缓存核验附件文件名、大小、消息 MD5（若存在），并计算 SHA256。

• 增量监听多个会话，记录每个消息分片的游标，重启继续读取；首次建立历史基线，不补发历史通知。

• 消息与文件就绪事件进入 SQLite 持久队列，消费者显式确认；MCP 只提供查询，不消费队列。

• 从加密 DB/WAL 临时副本查询；SQLCipher 密钥通过标准输入传递，不放入命令参数或查询结果。

Related MCP server: wechat-msg-mcp

环境

Python 3.12+，使用 uv 管理；macOS 上需要 SQLCipher 4。读取逻辑最初在 macOS Apple Silicon、微信 4.1.13 和 SQLCipher 4.19 上验证。本仓库测试使用自动生成的加密数据，不包含真实聊天记录。其他微信版本的兼容性需要实测，不能推断为全部支持。

快速开始

brew install uv sqlcipher
git clone https://github.com/zgkthu23/wechat-local-reader.git
cd wechat-local-reader
uv sync --locked
mkdir -p ~/.config/wechat-local-reader
chmod 700 ~/.config/wechat-local-reader
cp examples/config.example.json ~/.config/wechat-local-reader/config.json
chmod 600 ~/.config/wechat-local-reader/config.json

编辑仓库外的配置，设置自己的数据库目录、已有密钥文件和授权会话。密钥格式见配置说明。示例中的 ACCOUNT 和会话名称必须替换。

uv run wechat-reader messages --chat '示例项目群' --limit 20
uv run wechat-reader files --chat '示例项目群'
uv run wechat-reader poll
uv run wechat-reader watch

poll 执行一次检查，watch 按配置间隔持续检查，按 Ctrl-C 停止。安装项目本身不会注册后台任务或启用通知。后台运行见 macOS 部署。

通知由你自己的消费者读取：

uv run wechat-reader notifications --limit 100
# 将本批内容成功交付后，用该批返回的 through 数值确认：
uv run wechat-reader ack --through 12

12 只是示例。每个状态目录只运行一个通知消费者；失败时不确认，下次可重试。该项目本身不向任何聊天软件、远程服务器或 AI 模型发送消息。

Python API

from wechat_local_reader import Client, Config

client = Client(Config.load())
result = client.messages("示例项目群", limit=20)
files = client.files("示例项目群")
health = client.watcher.status()

MCP

通用 MCP 客户端使用下面的 stdio 配置，替换仓库绝对路径：

{
  "mcpServers": {
    "wechat-local-reader": {
      "command": "uv",
      "args": ["run", "--locked", "--directory", "/absolute/path/wechat-local-reader", "wechat-reader", "mcp"]
    }
  }
}

提供 read_wechat_messages、list_wechat_files、get_wechat_watch_status 三个工具。支持 WECHAT_READER_CONFIG 环境变量。配置 MCP 客户端后，查询结果会提供给该客户端；请按自己的数据使用要求配置客户端。

文档与开发

• 配置、授权和密钥格式

• CLI、Python、MCP 接口与通知数据格式

• 架构与监听语义

• macOS 后台运行、迁移与排障

• 安全与数据边界、参与开发

uv sync --locked
uv run ruff check .
uv run ruff format --check .
uv run pytest -q
uv build --no-sources

目录：src/wechat_local_reader/ 是配置、快照、读取、监听及接口实现；tests/ 是合成数据测试；docs/ 是部署和接口文档；examples/ 只含虚构配置。

范围

只覆盖当前电脑同步的记录；不能补齐手机历史或下载尚未缓存的云端文件。图片、语音、视频和表情返回类型标记，未实现媒体解码或转写。普通文件采用本地校验；无消息 MD5 时，只能通过唯一文件名和大小关联，输出会明确标为 unique_filename_size。

MIT 许可证。项目整理自本地独立编写的读取与监听实现，相关研究来源见 NOTICE。