# 微信本地聊天记录 MCP

> [!WARNING]
> **请先理解数据边界。** 本项目不会主动上传微信数据库或数据库密钥，但 MCP
> 返回给 Agent 的所选消息、图片、附件、语音转写和链接正文，会进入 Agent
> 主机的模型上下文。如果 Agent 使用云端模型，这些内容可能被发送给对应的模型
> 提供商。
>
> **不要通过 API 中转、第三方代理、聚合路由、共享网关或来源不明的 OpenAI
> 兼容接口使用本项目。** 中转服务可能记录、缓存或保留聊天内容，而本项目无法
> 审计或控制其数据处理方式。本项目仅推荐与**完全在本机运行的推理模型**配合
> 使用，使消息内容不离开设备。使用任何云端模型前，请自行确认提供商的数据
> 政策，并视为聊天内容可能离开本机。

这是一个本地优先、仅使用 stdio 的只读 MCP，让 Agent 查询和总结电脑所有者
自己的微信聊天记录。它支持稳定的日期与时间范围分页、批量群聊工作流、未读与
增量事件查询、上下文、结构化消息详情、按需媒体地址，以及受显式开关控制的
OCR、附件文本、语音转写和链接抓取。

本项目是独立社区项目，与腾讯或微信没有隶属或背书关系。仅可访问你本人拥有或
已获得明确授权的数据，并遵守当地法律及适用条款。

## 隐私建议

即使使用本机模型，也应遵循最小化原则：

- 先限定聊天、日期、时间范围和关键词，不要无目的地读取全部历史。
- 先用 `count_messages` 估算规模，再以 `compact=true` 分页读取。
- 大群聊逐页总结，只把与当前问题相关的摘要保留在模型上下文中。
- 不需要身份追踪时，不在报告中保留账号 ID、数据库路径或其他稳定标识。
- 图片和表情只返回轻量引用；仅让 Agent 打开与当前问题有关的单张图片。
- 表情默认为低优先级，除非用户明确询问，或缺少表情就无法理解语义，否则跳过。
- OCR、附件全文、语音转写、媒体派生写入和网络抓取只在确有需要时开启。
- 不要把数据库、密钥、原始聊天导出、解码媒体或运行日志上传到 Issue、PR、网盘
  或其他外部服务。

## 让 Agent 安装

可以把下面的指令交给具备本机安装能力的 Agent：

```text
克隆 https://github.com/hetiankong/wechat-local-agent-mcp，完整阅读
AGENTS.md，并按其中流程安装和验证本地只读微信 MCP。安装期间不要输出
数据库密钥、账号标识或消息内容。
```

`AGENTS.md` 是完整的安装决策树、安全合同、验证清单、排障指南和大群聊读取
流程。

### macOS Apple Silicon

```bash
git clone https://github.com/hetiankong/wechat-local-agent-mcp.git
cd wechat-local-agent-mcp
./scripts/install.sh --register-codex
./scripts/bootstrap-macos.sh
```

### Windows 11 amd64

```powershell
git clone https://github.com/hetiankong/wechat-local-agent-mcp.git
cd wechat-local-agent-mcp
.\scripts\install.ps1 -RegisterCodex
```

安装器会下载官方 `r266-tech/wechat-cli` 运行包，并校验发布方提供的 `.sha256`
配套校验文件；校验不通过时会直接停止。本仓库不包含微信数据库、密钥、解码媒体、
消息或账号标识。离线环境可以通过 `WECHAT_CLI_RELEASE_ZIP` 和
`WECHAT_CLI_RELEASE_SHA256` 提供运行包及校验文件，校验要求不会因此降低。

## 核心工具

- `resolve_chat`、`sessions`、`search`、`timeline`
- `read_chat_day`、`read_chat_range`、`read_multiple_chats_day`
- `count_messages`、`unread`、`read_events`、`group_members`
- `context`、`message_details`、`message_media`

以下工具默认受独立开关控制：

- `ocr_message_images`
- `extract_message_files`
- `transcribe_message_voice`
- `fetch_message_links`

普通紧凑读取不会返回媒体路径、二进制负载、base64 或调试与密钥字段。

## 按需读取媒体

紧凑时间线使用轻量 `media_ref` 区分图片和表情：

- 图片为普通优先级，仅在与用户问题相关时调用 `message_media`。
- 表情为低优先级，默认不加载、不派生、不重复尝试。
- `message_media` 每次最多返回八个经过白名单验证的本地文件地址。
- 图片字节和 base64 不会进入普通聊天分页结果，因此不会提前消耗图片 Token。

选中的加密图片需要生成本地可读副本时，可调用：

```text
message_media(..., allow_derived_write=true)
```

此操作要求操作者预先启用 `WECHAT_MCP_ENABLE_DERIVED_WRITES=1`，并且只应对
已选中的单条图片消息调用一次。它可能创建私有解码缓存，但不会修改微信数据库。
OCR 仍需单独开启。

## 读取大群聊

例如读取某个群今天的全部消息，可以告诉 Agent：

```text
读取“项目群”今天的全部消息。先 resolve_chat 和 count_messages，再循环
read_chat_day(limit=200)，每次使用 next_cursor，直到 done=true。逐页总结后按
时间顺序合并，重要结论保留消息 ID、发送者和时间。图片只在与结论相关时按需读取，
表情默认跳过。
```

九百条消息通常需要约五次有界 MCP 调用。不要只读第一页，也不要在一次工具调用中
请求全部消息。`period` 支持 `today/今天`、`yesterday/昨天`、
`this_week/本周`、`last_week/上周`、最近若干小时或任意 `YYYY-MM-DD`。

## 安全边界

- 微信源数据库始终以只读方式打开。
- 核心子进程使用参数数组、`shell=False`、关闭的标准输入、超时、输出上限和命令
  白名单。
- 只有单独启用派生写入时，选中的媒体才可能生成私有本地缓存文件。
- 紧凑时间线只携带媒体提示；`message_media` 按需返回数量受限的本地地址。
- MCP 不提供通用 SQL、通用命令执行、导出、发送或回复消息、微信界面控制及无限
  监听功能。
- MCP 只允许本地 stdio，不得暴露为 HTTP 或 SSE 服务。
- macOS 初始化保持 SIP 开启，并使用受管理的影子微信，不重新签名已安装的原版
  微信。
- 经过审阅的 `wxkey` 补丁不会接收或保存管理员密码；认证由 macOS 系统窗口处理。
- 链接联网抓取默认关闭，并限制凭据、私有 IP、不安全跳转、非文本内容和过大响应。

安全问题及数据处理细节见 [SECURITY.md](SECURITY.md)。

## 本地开发

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e . pytest
.venv/bin/python -m pytest -q
```

Python 单元测试和安全测试不需要真实微信数据。涉及真实数据的验收只能输出计数、
布尔值和字段名，不得输出账号标识、聊天名称、消息正文、数据库路径或密钥。

## 致谢

本项目的查询运行时和密钥初始化建立在
[`r266-tech/wechat-cli`](https://github.com/r266-tech/wechat-cli) 与
[`r266-tech/wxkey`](https://github.com/r266-tech/wxkey) 的工作之上。架构还参考了：

- [`labazhou2024/chatlog-keeper`](https://github.com/labazhou2024/chatlog-keeper)
- [`Thearas/wechat-db-decrypt-macos`](https://github.com/Thearas/wechat-db-decrypt-macos)
- [`tomqiaozc/wx-dump-mac`](https://github.com/tomqiaozc/wx-dump-mac)
- [`cocohahaha/wechat-decrypt-macos`](https://github.com/cocohahaha/wechat-decrypt-macos)
- [`ylytdeng/wechat-decrypt`](https://github.com/ylytdeng/wechat-decrypt)

许可证和第三方组件的准确使用范围见
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。