Skip to main content
Glama
Wechat-MCP

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) 提供。