Weread MCP Worker

WeRead MCP Worker

把微信读书接入 ChatGPT / OpenAI Remote MCP 的单用户 Cloudflare Worker。

这个项目会把你的微信读书 Agent API Key 加密进 MCP URL 路径，例如：

https://your-worker.example.workers.dev/mcp/v1_<encrypted-token>

ChatGPT 添加这个远程 MCP Server 后，Worker 会在每次 MCP 请求中从 URL 路径解密出微信读书 API Key，再通过微信读书 Agent API Gateway 读取你的书架、笔记、划线、阅读统计等数据。

[!WARNING] 生成后的 MCP URL 是敏感凭据。虽然路径里存放的是密文，但这个 URL 仍然等价于访问你微信读书数据的 bearer token。不要公开、截图、发给别人或提交到 GitHub。

功能特性

• 部署在 Cloudflare Workers。
• 单用户设计，不需要数据库、KV、D1 或 R2。
• Setup 页面生成加密 MCP URL。
• 微信读书 API Key 不写入仓库，不写入 wrangler.toml。
• 支持 ChatGPT Developer Mode 的完整 MCP tools。
• 额外提供 search / fetch 两个兼容工具，方便符合 OpenAI data-only MCP 约定的场景。
• 只读能力；不提供写入书架、修改笔记、删除数据等操作。
• 一键安装脚本：scripts/install.sh。
• 发布 GitHub 前的敏感信息检查脚本：scripts/check-secrets.sh。

当前支持的微信读书能力

本项目基于 https://cdn.weread.qq.com/skills/weread-skills.zip 中的微信读书 Skill 文档实现。

统一微信读书网关

POST https://i.weread.qq.com/api/agent/gateway

请求头：

Authorization: Bearer $WEREAD_API_KEY
Content-Type: application/json

请求体规则：

{
  "api_name": "/store/search",
  "keyword": "三体",
  "count": 10,
  "skill_version": "1.0.4"
}

重要规则：业务参数必须与 api_name、skill_version 平铺在同一层，不能包进 params。

MCP tools

工作原理

sequenceDiagram
  participant User as 你
  participant Setup as Worker /setup
  participant ChatGPT as ChatGPT MCP Client
  participant Worker as Cloudflare Worker MCP
  participant WeRead as 微信读书 Agent API Gateway

  User->>Setup: 输入 Setup 密码和微信读书 API Key
  Setup->>Setup: 用 WEREAD_MCP_ENCRYPTION_KEY 加密 API Key
  Setup-->>User: 返回 /mcp/v1_encrypted_token
  User->>ChatGPT: 添加远程 MCP Server URL
  ChatGPT->>Worker: POST /mcp/v1_encrypted_token JSON-RPC initialize/tools/list/tools/call
  Worker->>Worker: 解密 URL token 得到 API Key
  Worker->>WeRead: POST /api/agent/gateway Authorization: Bearer API Key
  WeRead-->>Worker: 返回微信读书数据
  Worker-->>ChatGPT: 返回 MCP tool result

安全模型

这个项目保护什么？

• 微信读书 API Key 不会明文出现在 Git 仓库里。
• API Key 不会明文保存在 Worker 配置文件里。
• URL 路径里的 API Key 使用 Worker Secret WEREAD_MCP_ENCRYPTION_KEY 加密。
• Worker 代码不主动记录完整 URL、API Key 或加密 token。

这个项目不保护什么？

• 生成后的 MCP URL 本身仍然是敏感凭据。任何拿到 URL 的人都可以使用这个 MCP Server。
• 如果你开启了 Cloudflare 访问日志、边缘日志、第三方代理日志，完整 URL path 可能被平台或代理记录。
• 如果你把生成后的 MCP URL 复制给别人或提交到 GitHub，密文路径就泄露了。
• 这是单用户设计，不是多租户权限系统。

建议

• 只把 Worker 部署给自己使用。
• 不要分享生成后的 MCP URL。
• 不要把 .dev.vars、.env、真实 API Key、真实 MCP URL 提交到 GitHub。
• 如果怀疑 URL 泄露，立刻重新设置 WEREAD_MCP_ENCRYPTION_KEY，重新部署并重新生成 MCP URL。
• 定期更新微信读书 API Key 和 MCP URL。

前置条件

• Node.js 20+。
• npm。
• Cloudflare 账号。
• 已登录 Wrangler，或允许安装脚本打开 Wrangler 登录流程。
• 微信读书 API Key，格式通常类似 wrk-...。

快速开始：一键安装

git clone https://github.com/<your-name>/weread-mcp-worker.git
cd weread-mcp-worker
./scripts/install.sh

脚本会做这些事：

1. 安装 npm 依赖。
2. 询问 Worker 名称。
3. 检查 Wrangler 登录状态。
4. 生成随机 WEREAD_MCP_ENCRYPTION_KEY。
5. 询问或自动生成 WEREAD_MCP_SETUP_PASSWORD。
6. 部署 Cloudflare Worker。
7. 通过 wrangler secret put 上传 Worker secrets。
8. 输出 /setup 页面地址。

安装完成后打开：

https://<your-worker>.workers.dev/setup

输入：

• Setup 密码。
• 微信读书 API Key。

然后复制页面生成的 MCP URL。

手动部署

1. 安装依赖

npm install

2. 登录 Cloudflare

npx wrangler login

3. 设置 Worker secret

生成加密密钥：

node scripts/generate-secret.mjs

设置 secrets：

npx wrangler secret put WEREAD_MCP_ENCRYPTION_KEY
npx wrangler secret put WEREAD_MCP_SETUP_PASSWORD

也可以使用密码 hash，而不是保存明文 Setup 密码：

printf 'your-setup-password' | node scripts/generate-secret.mjs sha256
npx wrangler secret put WEREAD_MCP_SETUP_PASSWORD_SHA256

如果同时设置了 WEREAD_MCP_SETUP_PASSWORD_SHA256 和 WEREAD_MCP_SETUP_PASSWORD，Worker 会优先使用 hash。

4. 部署

npm run deploy

5. 生成 MCP URL

打开：

https://<your-worker>.workers.dev/setup

输入 Setup 密码和微信读书 API Key，获得：

https://<your-worker>.workers.dev/mcp/v1_<encrypted-token>

在 ChatGPT 中添加 MCP Server

截至 2026-05-16，OpenAI 文档中 ChatGPT Developer Mode 支持完整 MCP client，可在 ChatGPT 设置中导入远程 MCP Server，并支持 SSE 和 Streamable HTTP。本项目实现的是 Streamable HTTP JSON response 模式：

• POST /mcp/<token>：MCP JSON-RPC 请求。
• GET /mcp/<token>：返回 405 Method Not Allowed，表示不提供 SSE stream。

一般步骤：

1. 打开 ChatGPT。
2. 进入 Settings。
3. 打开 Connectors。
4. 在 Advanced 中启用 Developer mode。
5. 在 Connectors tab 添加远程 MCP Server。
6. 填入 /setup 生成的 MCP URL。
7. 保存后，在对话里的 Developer Mode / Connectors 工具中启用这个 server。

测试问题示例：

列出我的微信读书书架前 10 本书。

总结一下我的微信读书阅读概况。

帮我看看我在《三体》里的划线和想法。

统计我今年在微信读书读了多久。

OpenAI API 远程 MCP 示例

如果你想通过 Responses API 测试远程 MCP，可参考下面形式。这里的 server_url 使用 /setup 生成的完整 MCP URL。

{
  "type": "mcp",
  "server_label": "weread",
  "server_url": "https://<your-worker>.workers.dev/mcp/v1_<encrypted-token>",
  "require_approval": "never"
}

如果只想使用 data-only 兼容工具，可以限制：

{
  "type": "mcp",
  "server_label": "weread",
  "server_url": "https://<your-worker>.workers.dev/mcp/v1_<encrypted-token>",
  "allowed_tools": ["search", "fetch"],
  "require_approval": "never"
}

本地开发

复制本地变量模板：

cp .dev.vars.example .dev.vars

编辑 .dev.vars，填入仅用于本地开发的值。

启动开发服务器：

npm run dev

打开：

http://localhost:8787/setup

Smoke test

生成 MCP URL 后，可以测试初始化和 tools 列表：

node scripts/smoke-test.mjs 'https://<your-worker>.workers.dev/mcp/v1_<encrypted-token>'

这个脚本会调用：

• initialize
• notifications/initialized
• tools/list

它不会调用微信读书 API，因此不会验证 API Key 是否有效。要验证微信读书 API Key，请在 ChatGPT 或 MCP 客户端里调用一个真实工具，例如 weread_get_bookshelf。

开发命令

npm run typecheck
npm test
npm run check
npm run deploy

配置项

微信读书接口注意事项

API Key

微信读书 Skill 文档说明 API Key 来自环境变量 WEREAD_API_KEY，格式通常是：

wrk-xxxxxxxx

本项目不需要你把这个值设置成 Worker secret。你只需要在 /setup 页面输入它，Worker 会把它加密进生成的 MCP URL。

skill_version

当前从 zip 中识别到的版本是：

1.0.4

如微信读书接口返回 upgrade_info，说明上游 Skill 版本要求变化，需要更新项目中的 WEREAD_SKILL_VERSION 或代码。

deepLink 规则

微信读书 Skill 1.0.4 要求优先使用接口回包中的 deepLink 字段。

本项目遵循该规则：

• 如果接口返回 deepLink，会原样保留并返回给 MCP 客户端。
• 如果接口没有返回 deepLink，项目不会主动拼接 weread:// 深度链接。
• 项目仍可能返回普通网页 webUrl，作为浏览器可打开的辅助链接。

weread_get_profile 默认行为

weread_get_profile 已按微信读书 Skill 1.0.4 调整为更轻量的默认行为：

• 默认 progressLimit = 5，只查询最近阅读的 5 本电子书进度。
• 默认 highlightCountLimit = 0，不额外逐本调用 /book/bookmarklist 统计划线数。
• 默认使用 /user/notebooks 返回笔记概览；如果需要单本书笔记内容，再调用 weread_get_book_notes。

笔记口径

/user/notebooks 中：

单本书总笔记数 = reviewCount + noteCount + bookmarkCount

其中：

• reviewCount：想法/点评数，包含划线想法、书评想法、书摘、非书籍想法等个人内容。
• noteCount：划线/高亮原文条数，不是单本书总笔记数。
• bookmarkCount：书签数量。当前接口只提供数量，不提供书签位置内容导出。

weread_get_book_notes 导出的内容范围是：

划线内容 + 想法/点评内容

不包含书签位置内容。

书架数量口径

书架总条目必须按下面规则计算：

books.length + albums.length + (mp 非空 ? 1 : 0)

其中：

• books[]：电子书/导入书/公众号类书籍条目。
• albums[]：专辑/有声书，也属于书架里的书。
• mp：文章收藏入口，非空时计为 1 个书架条目。

阅读时长

微信读书阅读统计中的时长字段以秒为单位。本项目会额外返回部分人类可读字段，例如：

2小时15分钟

发布到 GitHub 前检查

1. 确认 Git 状态

git status --short

2. 确认不会提交本地 secrets

git diff --cached

3. 运行项目内检查脚本

./scripts/check-secrets.sh

4. 可选：使用 gitleaks

gitleaks detect --source .

5. 不要提交这些内容

• .dev.vars
• .env
• 真实微信读书 API Key
• 真实 MCP URL
• Cloudflare API Token
• 任何 cookie 或 session 信息

故障排查

ChatGPT 无法连接 MCP Server

检查：

1. URL 是否是完整 /mcp/v1_<encrypted-token>，不是 /setup。
2. Worker 是否已经部署成功。
3. WEREAD_MCP_ENCRYPTION_KEY 是否已设置。
4. ChatGPT Developer Mode 是否已启用。
5. Worker 日志中是否有 401、403、500。

返回 Invalid MCP URL token

常见原因：

• 复制 URL 时漏了一部分。
• 重新设置过 WEREAD_MCP_ENCRYPTION_KEY，旧 URL 无法解密。
• URL 被聊天软件、Markdown 或浏览器自动换行截断。

解决：重新访问 /setup 生成 MCP URL。

Setup 页面提示密码错误

检查：

• WEREAD_MCP_SETUP_PASSWORD 是否正确。
• 如果使用 WEREAD_MCP_SETUP_PASSWORD_SHA256，确认 hash 是对原始密码计算的 SHA-256 hex。
• 如果两个变量都设置了，Worker 优先使用 WEREAD_MCP_SETUP_PASSWORD_SHA256。

微信读书认证失败

检查：

• API Key 是否有效。
• API Key 是否属于当前微信读书账号。
• 是否复制了多余空格或换行。
• 微信读书 Agent API 是否变更。

重新在 /setup 输入新的 API Key 生成 URL。

笔记或书架数据不完整

• weread_get_notebooks 使用 lastSort 游标分页，不支持 offset/limit。
• 大列表默认会限制返回数量，避免 MCP 响应过大。
• 需要全量笔记概览时，使用 fetchAll: true 和合理的 maxPages。

Worker 日志中是否会出现 API Key？

项目代码不会主动记录 API Key、加密 token 或完整请求 URL。但如果你启用了 Cloudflare 平台层请求日志，URL path 仍可能被记录。请按敏感信息处理生成后的 MCP URL。

非官方声明

本项目不是微信读书官方项目，也不是 OpenAI 官方项目。微信读书 Agent API 行为可能变化。请仅用于访问你自己的数据，并遵守微信读书相关服务条款、版权规则和使用限制。

License

MIT