WeChat Chat MCP
by Haoea1024
README.md
# WeChat Chat MCP
**让你正在使用的智能体去微信查资料:跨群聊和私聊找信息,按需读附件,保存有出处的项目资料。**
[](LICENSE)
[](pyproject.toml)
[](docs/INSTALL.md)
**安装前了解数据去向:**首次默认把本机近 30 天群聊和私聊同步到本地 SQLite,独立后台分析默认关闭。同步不调用模型;查询时工具返回的消息和附件会进入当前智能体上下文,是否发送到云端取决于客户端和模型设置。分页限制单次返回量,不限制整次查询累计读取量。[数据存放说明](#数据放在哪里)
项目名称为 **WeChat Chat MCP**,仓库名为 `wechat-chat-mcp`;Python 包名仍为 `wechat-project-assistant`,命令为 `wechat-assistant`,默认资料目录为 `~/.wechat-project-assistant`。这些名称指向同一项目,现有安装继续使用原命令和资料目录;网页中的“微信项目助理”是其项目资料界面。
## 直接发给智能体安装
在能执行**本机 Windows 命令**的 WorkBuddy 或 Codex 中发送:
> 请安装 https://github.com/Haoea1024/wechat-chat-mcp 并接入我当前使用的客户端。按照仓库 docs/INSTALL.md 完成安装和验证。
智能体负责检查环境、安装依赖、连接微信、同步本地索引和注册 MCP。微信登录、多个账户的选择及客户端要求的授权由你处理,无需自己填写 MCP 配置。
- **WorkBuddy 5.9.3**:2026-11-14 使用者验证当时的 20 个原生工具可见、`project_status` 原生调用成功;此后新增了用量统计工具,具体项目检索和媒体读取仍待逐项验证。
- **Codex**:提供同一安装脚本的自动注册入口;旧版已有本机使用验证,新版客户端读图需验收。DSH 暂不作为本轮适配目标。
WorkBuddy 5.9.3 的确认入口是 **「专家·技能·连接器 → 连接器 → 自定义连接器」**,首次连接按提示点击“信任”。安装程序完成配置写入后,还需在当前客户端通过原生工具调用验证;重启不代替信任。命令行入口只作授权后的辅助方式。只发链接可能被理解为阅读,建议带上“安装并接入当前客户端”。
已有安装可直接说:
> 请升级 wechat-chat-mcp:先检查本地修改、分支和远端,保留我的改动并拉取仓库最新版,再读新版 docs/INSTALL.md 完成当前客户端升级。保留原资料目录,刷新网页后台并重新连接 MCP,验证原生工具。以后查完我明确指定的项目,默认把有出处的资料保存到网页,无需再问我要不要保存。
[安装指南](docs/INSTALL.md) · [完整使用说明](docs/USAGE.md) · [工具与格式参考](docs/REFERENCE.md)
## 可以怎样用
> 帮我查“订单同步”项目最近的讨论,先找相关群,再补充成员私聊和遗漏会话,告诉我进展、分歧和需要我处理的事情。
> 把这个项目的重要附件备份到本机,下次先看新增和变更。
> 群里的方案后来改了,去读最新消息和对应文件,核对旧结论。
> 我只负责接口部分,测试验收由同事负责。请记住这个分工,后续不要把验收任务算到我头上。
首次使用不预设项目;明确指定项目查询后,智能体默认在回答前保存有出处的资料,网页直接展示,无需每次提醒。也可以说“只查不保存”;普通聊天查询不会自动建项目。
## 核心能力
| 能力 | 使用方式 |
| --- | --- |
| 跨会话查询 | 先按群名和项目别名发现候选,再从相关群成员找私聊;成员关系只作线索 |
| 按需读证据 | 分页读取正文、上下文和附件,保留消息 ID、会话、时间与来源 |
| 项目资料 | 项目查询后默认保存背景、进展、决定与疑问,网页同步展示;保留版本,下次补读新增或变更 |
| 附件副本 | 按准确消息关联、内容指纹保存本机副本;原文件不动,可继续按需读取 |
| 用户纠正 | 保存明确分工和线下补充,可查看、可撤销 |
| 本地增量索引 | 默认同步近 30 天到 SQLite;同步不调用模型,不把整月聊天塞进上下文 |
| 用量统计 | 网页“用量”查看调用次数、返回文字粗估 token 和图片数量;独立 API 的用量回执另列,不冒充账户扣费 |
默认先恢复项目资料、补读本地库中的新增和变更;微信源数据能否被采集受[同步范围](docs/REFERENCE.md#同步范围与变更检测)限制。同一次查询可复用已完整返回的聊天,只重复返回出处;新问题重新读取,原文变化或主动核对时仍可补读全文。项目列表和附件目录只返回必要信息,不顺带塞入所有历史概览或附件正文。[节省上下文的规则](docs/REFERENCE.md#减少重复读取)。
支持图片、语音、PDF、Word、PowerPoint、Excel、文本和 ZIP;具体格式、依赖及部分读取限制见[附件说明](docs/REFERENCE.md#图片语音与文件)。资料摘要不替代原文,关键细节、矛盾和重要决定仍需回查证据。当前使用关键词与会话关联检索,没有向量数据库。
## 环境与边界
- 当前是 **Windows 优先的开发者预览版本**,读取能力受微信版本、本机同步与下载情况影响;不是微信官方插件。
- 微信数据库必须在运行服务的本机可访问;云端智能体不能仅凭仓库地址读取你的电脑。
- **默认无需额外 Codex CLI 或 API 密钥**:图片、扫描页和文档插图直接交回当前客户端识读。语音由本机 Whisper 转写,安装阶段下载并测试模型,查询时不临时下载。客户端仍需支持读图,实际展示与识读要验收。
- 未下载、已清理、缺失、失败或仅部分读取会明确标注;视频解析暂未实现,旧 DOC/PPT 转换需要可用的 Office/WPS。
- 默认由当前客户端查询、总结并保存资料;网页用项目卡片展示进展、下一步和待确认事项,完整资料与出处点开查看;更新时引导回当前对话。独立后台分析是可选项,普通 MCP 查询不需要一直开网页。
## 数据放在哪里
资料、配置与缓存默认在 `~/.wechat-project-assistant`,微信访问配置由上游组件保存在用户目录;均不应提交到仓库。附件副本仍是本机备份,不是异地备份。
同步本身不调用模型,但工具返回的聊天和附件内容会进入当前智能体的模型上下文;默认图片也交给当前客户端;仅显式启用独立模型时才使用额外模型入口。是否发送到云端取决于所用模型和客户端设置。本地保存不等于所有推理都在本机执行。
用量从升级并重新连接 MCP 后开始记录,也可直接问智能体“查看插件最近 7 天的用量”。统计本身不调用模型,只保存本机计数;文字粗估不含历史上下文、客户端思考/回答和图像 token,不能换算为 WorkBuddy 积分或 Codex 套餐余额。详见[统计口径](docs/REFERENCE.md#用量统计)。
## 开发与反馈
```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
powershell -NoProfile -ExecutionPolicy Bypass -File tests\test_install.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tests\test_native_command.ps1
```
测试使用虚构数据;[代表性查询核验](docs/REFERENCE.md#代表性查询核验)记录固定检索步骤能取得的证据与缺口,不代表模型自主查询准确率。欢迎用 Issues 反馈操作系统、微信版本、客户端版本、复现步骤与脱敏错误;不要附聊天数据库或密钥。当前由维护者独立写入,不接受外部 PR,公开源码可下载和 Fork。实现约定见 [AGENTS.md](AGENTS.md)。
## 致谢与许可证
采用 [Apache-2.0](LICENSE)。基于 [huohuoer/wechat-cli](https://github.com/huohuoer/wechat-cli) 的数据库访问与解码能力,参考 wechat-cli-plus 和 wechatauto-replica 的 Windows 与图片兼容实现,使用 MCP Python SDK、faster-whisper 及文档解析依赖。
上游说明见 [UPSTREAM_README.md](UPSTREAM_README.md),具体来源与改动归属见 [NOTICE](NOTICE)。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues