微信读书 · 远程 MCP

把微信读书官方网关的能力包成 远程 MCP。手机 App 等没有本地沙箱的前端，填一个 URL + 口令就能调用（不需要在你手机上跑任何进程）。

同一个能力，提供两种运行形态，按你的部署环境二选一：

⚠️ 两份代码不通用：Workers 版是 fetch handler，只能在 Cloudflare 跑；VPS/本机请用 server/。

• 传输：MCP Streamable HTTP（无状态），端点固定 /mcp

• 看板：内置 GET /dashboard，双 Tab（📖 共读 + 📚 书架与笔记），结构与桌面版 weread_dashboard.py 一致，手机浏览器直接打开

• 存储：MCP 端点不需要数据库，只有你的 wrk- key 放在服务端

• 工具：14 个，覆盖搜索 / 书架 / 笔记 / 阅读统计 / 点评 / 推荐

仓库结构

├── LICENSE         # MIT
├── src/            # Cloudflare Workers 版（wrangler 入口）
│   ├── index.js    #   MCP 服务 + /dashboard 路由
│   └── dashboard.js #  看板渲染（两种形态共用；结构与原版 weread_dashboard.py 一致）
├── wrangler.toml   #   └ Workers 配置
├── server/         # Node 版（Express + Streamable HTTP）—— VPS / 本机用
│   ├── src/        #   服务 + 网关客户端 + dashboard.js
│   ├── Dockerfile
│   └── .env.example
├── tools/
│   └── coread-export.py   # 把 EPUB 共读库（book.json/segments.db）导出成 coread.json
├── deploy/         # VPS 部署配置
│   ├── docker-compose.yml   # app + Caddy（自动 HTTPS）
│   ├── Caddyfile
│   ├── .env.example
│   └── systemd/weread-mcp.service   # 不用 Docker 时用
├── docs/
│   ├── 部署-VPS.md
│   └── 部署-自己电脑.md
└── test/           # Worker 版烟测

Related MCP server: mcp-server-weread

选哪条路？

一、部署到 Cloudflare Workers

一键部署（最简单）

本仓库顶部有按钮：

1. 点 Deploy to Cloudflare Workers。

2. 授权 Cloudflare → 自动 clone、构建、部署（无需本地环境）。

3. 部署完在 Cloudflare 后台给 Worker 加两个 Secret（见下方「设置密钥」）。

命令行部署

git clone https://github.com/Git-xian/weread-mcp-worker.git
cd weread-mcp-worker
npm install
npx wrangler login                        # 浏览器授权一次
npx wrangler secret put WEREAD_API_KEY    # 粘贴你的 wrk- key
npx wrangler secret put MCP_AUTH_TOKEN    # 自定义一串随机口令，手机端要用
npx wrangler deploy

部署成功会打印形如 https://weread-mcp.<子域>.workers.dev 的地址，MCP 端点即 .../mcp。

本地先跑通

cp .dev.vars.example .dev.vars   # 填 WEREAD_API_KEY 和 MCP_AUTH_TOKEN
npx wrangler dev                 # http://127.0.0.1:8787/mcp

设置密钥

两个 Secret（Cloudflare 后台 → Workers → 你的 Worker → Settings → Variables and Secrets，或 wrangler secret put）：

未设置 MCP_AUTH_TOKEN 时端点不鉴权，仅适合本机调试。

国内访问提示

*.workers.dev 在中国大陆常被墙。两个办法：

1. 绑定自有域名：Cloudflare 后台 → 你的 Worker → Settings → Domains & Routes → 添加自定义域（域名需已接入 Cloudflare）。

2. 改用 VPS/本机（server/）：直接用你自己的域名，绕开这个墙。

二、部署到 VPS 或自己电脑

用 server/（Node 版）。完整步骤见教程：

• VPS：docs/部署-VPS.md —— Docker Compose + Caddy 自动 HTTPS，一条命令起服务；也含 systemd / Nginx 反代方式。

• 自己电脑：docs/部署-自己电脑.md —— 本机直跑 + 局域网访问 + 内网穿透（Cloudflare Tunnel / Tailscale / frp）拿 https 域名。

最短路径（VPS，Docker）：

git clone https://github.com/Git-xian/weread-mcp-worker.git
cd weread-mcp-worker/deploy
cp .env.example .env && vi .env     # 填 MCP_DOMAIN / WEREAD_API_KEY / MCP_AUTH_TOKEN
docker compose up -d --build
# 手机端：https://你的域名/mcp  +  Authorization: Bearer <口令>

最短路径（自己电脑）：

cd weread-mcp-worker/server
npm install
cp .env.example .env && vi .env     # 填 WEREAD_API_KEY / MCP_AUTH_TOKEN（HOST 设 0.0.0.0 供局域网访问）
npm run start:env

手机端接入（通用）

在支持「远程 MCP」的 App 里添加服务器：

• 类型：Streamable HTTP / 远程 MCP（不要选 stdio）

• URL：https://<你的地址>/mcp

• 请求头：Authorization: Bearer <你的 MCP_AUTH_TOKEN>

之后就能直接问，比如「看看我的书架」「我这个月读了多久」「三体有什么点评」。

提供的工具（tools）

看板（共读 + 书架）

除了 MCP 工具，服务还内置一个看板页面（GET /dashboard），结构与桌面版 weread_dashboard.py 完全一致：顶部双 Tab —— 📖 共读 / 📚 书架与笔记。

• 端点：GET /dashboard

• 口令：?token=<你的 MCP_AUTH_TOKEN>（与 MCP 同一个口令）

• 可选：?books=<1..20>，最多渲染多少本有笔记的书（默认 12）

https://<你的地址>/dashboard?token=<MCP_AUTH_TOKEN>

📚 书架与笔记（数据实时来自官方网关） 汇总行 + 搜索框 + 书脊色条书卡；点书名展开该书的划线 🟡 / 想法 💭，每条下方预留 🔵 助手批注位。

📖 共读（需注入共读数据，见下） 原版书逐段对照，点任意段落 → 写 🟡你的 / 🔵助手的批注；本机自动暂存，可「下载批注」导出 JSON。

共读数据怎么来

共读页需要 EPUB 拆段数据（网关不提供正文）。用本地脚本把 EPUB 拆好，再导出成看板能吃的 JSON：

# 1) 拆 EPUB（epub_split.py，来自原项目）
python epub_split.py 你的书.epub --out ./weread-data/books/你的书

# 2) 导出成 coread.json（含已有批注）
python tools/coread-export.py ./weread-data/books/你的书 coread.json --b64

# 3) 注入看板（三选一）
#    a. Node 版：环境变量 COREAD_FILE=coread.json
#    b. URL 内联：/dashboard?token=xxx&coread=<上面 --b64 的输出>
#    c. Cloudflare：把 coread.json 存进 KV 绑定的 "coread" 键

未提供共读数据时，看板为单页书架模式（共读 Tab 显示占位）。

⚠️ 看板含你的真实划线 / 想法 / 批注，务必带 token 打开，不要把带 token 的链接外发。

📌 子请求预算：书架页每本书要拉 2 次网关（划线 + 想法）。Cloudflare Workers 免费版单请求上限 50 个子请求 → books 别调太大（默认 12 约 27 个子请求，安全）；书特别多时绑付费版或加 KV 缓存。

安全边界

• WEREAD_API_KEY 只存在于服务端（Worker Secret / 服务器 .env），不进代码、不进日志、不进任何回包。

• 端点鉴权靠 MCP_AUTH_TOKEN，务必设置，且不要在公开场合贴出来。

• 本服务只做读类转发，不落地任何数据；共读批注等私有数据仍留在你本机。

• Node 版部署时，应用只监听 127.0.0.1:8787，公网仅暴露 443（见 VPS 教程「安全清单」）。

• skill_version 固定为 1.0.4；若官方网关返回 upgrade_info，按提示更新 src/weread.js（Worker）或 server/src/weread.js 顶部的 SKILL_VERSION。

参考与致谢

本项目的共读形态与看板设计，站在这些开源项目与官方服务的肩膀上：

本仓库代码为原创实现，仅调用官方公开接口，未复制上述任何项目的源码。

开源协议

MIT © 2026 weread-mcp-worker contributors