Wechat-MCP
by willwill85
README.md
# Wechat-MCP
把本机微信消息每 10 分钟同步成本地索引,并通过 MCP(Model Context Protocol)提供给 AI Agent 只读访问。
- **100% 本地只读**:服务仅监听 `127.0.0.1:39765`,聊天数据库与索引只保存在本机用户目录,不上传云端。
- **零侵入解密依赖**:依赖同级目录的 [fangtimmy/wechat4-db-decrypt](https://github.com/fangtimmy/wechat4-db-decrypt) 负责解密,本仓库不包含任何密钥、解密脚本或个人配置。
- **开箱即用**:内置 `launchd` 后台保活 + macOS 原生 Dock 控制台应用「微信MCP」+ 本地网页状态面板。
---
## 前置条件
- macOS,微信 4.x 桌面版已登录
- 已安装 [uv](https://docs.astral.sh/uv/) 与 Xcode Command Line Tools(`xcode-select --install`)
- 目录结构:`wechat4-db-decrypt/` 与 `wechat-mcp/` 需位于**同一父目录下**(`pyproject.toml` 通过 `../wechat4-db-decrypt` 引用可编辑依赖 `wxexport`)
---
## 快速安装
### 方式一:一键安装脚本(推荐)
```bash
git clone https://github.com/willwill85/Wechat-MCP.git wechat-mcp
cd wechat-mcp
./scripts/setup.sh
```
`scripts/setup.sh` 会自动检查 macOS 环境与 `uv`/Xcode CLT,在同级目录拉取 `fangtimmy/wechat4-db-decrypt`(若缺失),安装依赖并引导完成首次密钥抓取,随后安装后台服务与「微信MCP」应用。
> **提示**:首次抓取解密密钥前,请先为当前终端授予「完全磁盘访问权限」(系统设置 → 隐私与安全性 → 完全磁盘访问权限),并准备在弹出的调试副本中扫码登录一次。
### 方式二:手动分别安装
1. 在同一父目录下分别克隆两个仓库:
```bash
git clone https://github.com/fangtimmy/wechat4-db-decrypt.git wechat4-db-decrypt
git clone https://github.com/willwill85/Wechat-MCP.git wechat-mcp
```
2. 先进入 `wechat4-db-decrypt` 完整运行一次 `./run.sh`,生成 `all_keys.json`(若调试副本签名报 team-identifier 权限问题,可在 `src/wxexport/sip/prepare.py` 的 `capture_entitlements` 中移除 `com.apple.developer.team-identifier`)。
3. 再进入 `wechat-mcp` 安装后台服务与 Dock 应用:
```bash
cd wechat-mcp
./scripts/install.sh # 安装或更新 LaunchAgent,并立即执行一次同步
./scripts/build_app.sh # 编译 /Applications/WeChat MCP.app 并固定到 Dock
```
---
## 组成
- `/Applications/WeChat MCP.app`(Dock 栏「微信MCP」):原生 macOS 控制台应用,点击即可自动确保服务启动、立即同步微信消息、查看实时状态
- `local.wechat-mcp.sync`:LaunchAgent,每 600 秒运行一次后台同步(优先通过已获完全磁盘访问权限的 `node` 引导 `scripts/run_sync.js`)
- `local.wechat-mcp.server`:LaunchAgent,常驻 `wechat-mcp-server`,监听 `http://127.0.0.1:39765/mcp`(同时在 `http://127.0.0.1:39765/` 提供网页控制台,优先通过 `scripts/run_server.js` 引导)
- 数据目录:`~/Library/Application Support/wechat-mcp/`(索引 `messages.sqlite`、`status.json`)
- 日志目录:`~/Library/Logs/wechat-mcp/`
---
## 授权(首次必须)
同步进程由 `launchd` 启动,需要读取微信容器目录,因此要单独授予「完全磁盘访问权限」:
1. 打开 **系统设置 → 隐私与安全性 → 完全磁盘访问权限**,点击 `+`
2. 在项目目录运行下面的命令,得到 venv 解释器的真实路径:
```bash
.venv/bin/python -c "import os,sys; print(os.path.realpath(sys.executable))"
```
3. 在文件选择窗口按 `Cmd+Shift+G`,粘贴上一步输出的路径并添加
4. 运行以下命令立即重试同步:
```bash
launchctl kickstart -k gui/$(id -u)/local.wechat-mcp.sync
```
未授权时 `sync_status` 的 `last_error` 会给出同样的提示,旧索引保持不变。
---
## 连接 AI 客户端(MCP)
服务使用 **Streamable HTTP** 传输,默认地址:`http://127.0.0.1:39765/mcp`(仅限本机访问,无需 token)。完整示例可参考 [examples/mcp-config.example.toml](examples/mcp-config.example.toml)。
- **Codex**:在 `~/.codex/config.toml` 中添加:
```toml
[mcp_servers.wechat]
url = "http://127.0.0.1:39765/mcp"
```
- **Claude Code**:在终端执行:
```bash
claude mcp add --transport http wechat http://127.0.0.1:39765/mcp
```
- **Grok Bot / 其他支持本地 MCP 的桌面客户端**:
请在同一台 Mac 上将本地 MCP Endpoint 配置为 `http://127.0.0.1:39765/mcp`;**不要**把它当作云端 / 远程连接器添加到服务端(本服务仅绑定 `127.0.0.1`)。
---
## MCP 工具
| 工具 | 作用 |
| --- | --- |
| `get_latest_messages(limit, hours)` | 所有会话最新消息,从新到旧 |
| `list_chats(query, limit)` | 按最近消息时间列出会话,可按名称或 wxid 过滤 |
| `get_chat_messages(chat, limit, before)` | 单个会话最近消息(正序),`before` 用于翻页 |
| `search_messages(keyword, chat, limit)` | 正文关键字搜索,可限定会话 |
| `sync_status()` | 最近一次同步时间、结果、消息数与错误信息 |
---
## 卸载
```bash
./scripts/uninstall.sh # 卸载两个 LaunchAgent,保留数据和日志
```
---
## 目录结构
```text
├── LICENSE # MIT 开源协议
├── pyproject.toml # 依赖(mcp<2,wxexport 为同级目录可编辑依赖)
├── uv.lock # 锁定的依赖版本
├── src/wechat_mcp/
│ ├── __init__.py # 版本号与构建时间
│ ├── config.py # 数据目录、端口(固定 127.0.0.1:39765)
│ ├── sync.py # 解密 → 建索引 → 原子替换 → 写状态
│ └── server.py # 只读 MCP 工具 + 本地可视化状态面板
├── macos/
│ ├── WeChatMCPApp.swift # Dock 原生控制台应用源码
│ └── make_icon.swift # 应用图标生成脚本
├── launchd/*.plist.in # LaunchAgent 模板
├── scripts/
│ ├── setup.sh # 一键安装脚本(拉取解密依赖 + 密钥 + 服务)
│ ├── install.sh # 渲染模板并加载 LaunchAgent
│ ├── build_app.sh # 编译 WeChat MCP.app 并加入 Dock
│ ├── run_server.js # Node 启动包装器(服务进程引导)
│ ├── run_sync.js # Node 启动包装器(继承 TCC 磁盘权限)
│ └── uninstall.sh # 卸载 LaunchAgent
├── examples/
│ └── mcp-config.example.toml # Codex / Claude Code / Grok Bot 配置示例
├── docs/DESIGN.md # 设计决策与变更记录
└── README.md
```
---
## 注意
- 索引包含全部聊天正文,等同于明文聊天记录,只保存在本机用户目录(`~/Library/Application Support/wechat-mcp/`)中,不要提交或分享
- 同步不会抓取密钥,也不会退出微信。微信升级或账号迁移导致密钥失效时,`sync_status` 会报错,此时需在 `wechat4-db-decrypt` 中运行 `./run.sh --refresh-snapshot` 重新抓取密钥
- 媒体文件本体不导出,图片、语音等只有占位符
## 致谢
- 解密能力由 [fangtimmy/wechat4-db-decrypt](https://github.com/fangtimmy/wechat4-db-decrypt) 提供。