Skip to main content
Glama
Wechat-MCP

Wechat-MCP

by willwill85

Wechat-MCP

把本机微信消息每 10 分钟同步成本地索引,并通过 MCP(Model Context Protocol)提供给 AI Agent 只读访问。

  • 100% 本地只读:服务仅监听 127.0.0.1:39765,聊天数据库与索引只保存在本机用户目录,不上传云端。

  • 零侵入解密依赖:依赖同级目录的 fangtimmy/wechat4-db-decrypt 负责解密,本仓库不包含任何密钥、解密脚本或个人配置。

  • 开箱即用:内置 launchd 后台保活 + macOS 原生 Dock 控制台应用「微信MCP」+ 本地网页状态面板。


前置条件

  • macOS,微信 4.x 桌面版已登录

  • 已安装 uv 与 Xcode Command Line Tools(xcode-select --install)

  • 目录结构:wechat4-db-decrypt/ 与 wechat-mcp/ 需位于同一父目录下(pyproject.toml 通过 ../wechat4-db-decrypt 引用可编辑依赖 wxexport)


Related MCP server: wechat-local-mcp

快速安装

方式一:一键安装脚本(推荐)

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. 在同一父目录下分别克隆两个仓库:

git clone https://github.com/fangtimmy/wechat4-db-decrypt.git wechat4-db-decrypt
git clone https://github.com/willwill85/Wechat-MCP.git wechat-mcp
  1. 先进入 wechat4-db-decrypt 完整运行一次 ./run.sh,生成 all_keys.json(若调试副本签名报 team-identifier 权限问题,可在 src/wxexport/sip/prepare.py 的 capture_entitlements 中移除 com.apple.developer.team-identifier)。

  2. 再进入 wechat-mcp 安装后台服务与 Dock 应用:

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 解释器的真实路径:

    .venv/bin/python -c "import os,sys; print(os.path.realpath(sys.executable))"
  3. 在文件选择窗口按 Cmd+Shift+G,粘贴上一步输出的路径并添加

  4. 运行以下命令立即重试同步:

    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。

  • Codex:在 ~/.codex/config.toml 中添加:

    [mcp_servers.wechat]
    url = "http://127.0.0.1:39765/mcp"
  • Claude Code:在终端执行:

    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()

最近一次同步时间、结果、消息数与错误信息


卸载

./scripts/uninstall.sh   # 卸载两个 LaunchAgent,保留数据和日志

目录结构

├── 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 重新抓取密钥

  • 媒体文件本体不导出,图片、语音等只有占位符

致谢

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A read-only MCP server that enables searching and extracting to-dos from local macOS WeChat chat databases. It decrypts and queries local WeChat data without sending messages or modifying databases.
      12
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to query local WeChat chat data through read-only MCP tools, including sessions, messages, contacts, search, and statistics, with everything processed locally.
      75 PyPI
      6
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to list chats and groups, read full group history, search across message shards, and access summaries or system events from local WeChat 4.x data through a read-only, offline MCP interface.
      -