Goodreads MCP

📚 goodreads-mcp

感谢 Shreeya Chand。 本项目是 shreeyachand/goodreads-mcp 的分支，没有这项工作，本项目便不会存在。无需使用已停用的 Goodreads API 即可访问 Goodreads，这一核心构想以及本服务提供的工具集都源自 Shreeya 的项目。我们对此深表感谢，也感谢 MIT 许可证允许我们在此基础上继续构建。如果这个服务对你有用，请为原项目点个星。

这是一个面向 Goodreads 的只读 MCP 服务——无需 Goodreads API 构建，因为自 2020 年 12 月以来就没有可用的 API。它能让大模型查找和研究书籍、评分及书评。工具依托 RSS 源、JSON 自动补全端点、嵌入书籍页面中的 __NEXT_DATA__ 数据块，以及 Goodreads 网站本身使用的 AppSync GraphQL 后端运行。无需登录、无需 Cookie、不会写入数据——仅使用公开数据。

工具

工具	来源 / 返回内容
search_books	JSON 自动补全端点（稳定）——book_id、标题、作者、评分、封面；max_results 默认值为 10，但端点最多返回约 5 个匹配结果
get_book	通过 .xml 页面获取 __NEXT_DATA__（稳定）——详情、封面、评分分布、所属的所有系列、评论语言细分（review_language_limit 默认值为 5，最大值为 25）；版本的 publication_date 以及作品的 first_published、original_title、language、isbn / isbn13 / asin、author_url（缺失时各自为 null）
get_reviews	GraphQL——分页返回读者评论（文本、评分、点赞数、日期、剧透标记、永久链接）；limit 默认值为 10，上限为 100；服务端支持 min_rating / max_rating（1–5，且 min ≤ max）、sort（默认值为 relevance，还可选 newest、oldest）、language（两个字母的代码，与 get_book 的 review_languages 中所用代码相同）和按评论文本搜索的 search；支持 exclude_spoilers；返回 has_more
similar_books	GraphQL——分页返回“读者也喜欢”的推荐书目；limit 最大为 100
author_books	GraphQL——分页返回作者的书目，按受欢迎程度排序，涵盖作者的任意作品，并附带 author_url；limit 最大为 100
series_books	GraphQL——分页返回系列书目及其阅读顺序；series_index（从零开始，按 get_book 的 series_memberships 顺序排列）用于选择系列；limit 最大为 100
get_editions	GraphQL——分页返回各个版本（格式、ISBN、出版商、以 publication_date YYYY-MM-DD 格式表示的出版日期，以及以 epoch 毫秒表示的原始 publication_time）；limit 最大为 100
book_lists	GraphQL——分页返回收录该书的 Listopia 书单（标题、投票数、书单规模）；limit 最大为 100
popular_books	GraphQL——按发布年份 year（或指定单个月份 month，1–12）返回最受欢迎的书籍，并按受欢迎程度排序；limit 上限为 50
compare_books	对每个 id 调用 get_book（通过 .xml 获取 __NEXT_DATA__）——按评分对 1–10 本不同书籍排名，并返回好评/批评占比；重复的 id 只会获取一次；超过 10 个 id 时会拒绝请求；获取失败的书籍会以 error 条目返回
get_shelf	书架 RSS 源（稳定）——返回公开书架上的书籍（评分和年份为整数，缺失时为 None；日期格式为 YYYY-MM-DD；还包括 cover、pages、my_review）；page 从 1 开始，每页约 100 条；user_id 会覆盖已配置的用户；遇到私密个人资料时会引发 LoginRequired
list_shelves	尽力抓取公开个人资料页面的 HTML——返回书架名称；遇到私密个人资料时会引发 LoginRequired

每个工具都注册了 MCP 只读注解（只读、非破坏性、幂等）。

所有发现工具都接受 book_id，并返回带有 book_id / 标题 / 作者 / 评分 / URL 的结果，因此 Agent 可以串联调用——例如，对推荐书目调用 similar_books → get_reviews。book_id 在输入和输出中都是字符串（例如 "54493401"，输入时也可使用 "54493401-title" 这种 slug 形式），因此从一个结果中复制的值可以直接用于下一次调用。每个工具中的 average_rating 都是数字（或 null），因此可以将不同工具的结果放在一起排序。这就是通用网页搜索无法构建的结构化书籍图谱。

五个分页发现工具（similar_books、author_books、series_books、get_editions、book_lists）每批返回 20 条，并接受最高为 100 的总 limit；popular_books 的 limit 上限为 50。响应包含 returned 和 has_more，既能满足较大规模的查询需求，又可避免流量不受限制。

WAF 和登录说明： Goodreads 图书 HTML 页面现在受到 AWS WAF JavaScript 挑战（HTTP 202）的保护，普通 HTTP 客户端无法通过挑战。get_book 会通过带 .xml 后缀的页面绕过挑战，因此无需浏览器也能正常工作。如果 Goodreads 将来把 WAF 扩展到我们依赖的路径，客户端会抛出 WAFChallenge，并提供清晰的说明，而不是令人困惑的解析错误。评论列表页面（/review/list/{uid}）于 2026 年 9 月起仅限登录用户访问；出于同样的原因，客户端在遇到登录重定向时会抛出 LoginRequired，而 list_shelves 会改为读取公开个人资料页面。

安装

使用 pip：

cd goodreads-mcp
python3.11 -m venv .venv && .venv/bin/pip install -e .

或者使用 uv，Claude Desktop bundle 也使用它：

cd goodreads-mcp
uv sync
uv run goodreads-mcp

需要 Python ≥ 3.11。

每个按日期编号的版本也会以 goodreads-mcp-ai 的名称发布到 PyPI（该平台上的 goodreads-mcp 名称属于无关项目），并通过 server.json 列入官方 MCP 注册表，名称为 io.github.Danathar/goodreads-mcp-ai。该条目带有 uvx 运行时提示；遵循此提示的客户端会运行 uvx goodreads-mcp-ai，你也可以自行运行此命令。

配置（可选）

无需登录或 Cookie——所有数据均为公开数据。唯一的设置是数字形式的 user_id，它是书架工具的默认值。它是 goodreads.com/user/show/<ID>-yourname 中的数字；你也可以在每次调用书架工具时传入 user_id。

mkdir -p ~/.config/goodreads-mcp
cat > ~/.config/goodreads-mcp/config.json << 'EOF'
{ "user_id": "12345678" }
EOF

环境变量 GOODREADS_USER_ID 会覆盖配置文件。如果配置文件无法读取、不是有效的 JSON、不是 JSON 对象，或其中的 user_id 既不是字符串也不是整数，系统会忽略该文件并在 stderr 上发出警告（裸数字，例如 12345678，会被接受并以字符串形式使用；布尔值、浮点数、列表和对象则会被忽略）；服务仍会启动。

Claude Desktop 配置

Bundle。 每个版本都会附带一个 goodreads-mcp.mcpb。仅当服务本身有更改时，才会按月发布新版本，并按日期编号（2026.10.0、2026.10.1、2026.11.0）；旧编号中的最后一个版本是 0.1.1，所有按日期编号的版本都比它新。有关如何制作版本，请参阅 CONTRIBUTING.md。在 Claude Desktop 中打开 .mcpb 即可安装。Bundle 不包含依赖项——清单会使用 uv run 启动服务，主机会在首次启动时将 pyproject.toml 解析到私有环境中——因此，同一个 bundle 可在 macOS、Windows 和 Linux 上运行，且支持任意 Python ≥ 3.11。Bundle 的可选“Goodreads User ID”设置（user_config.goodreads_user_id）会作为 GOODREADS_USER_ID 传递给服务；若留空，则会传递空值，服务会回退到配置文件。

手动配置。 将服务添加到 claude_desktop_config.json——macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上的路径为 %APPDATA%\Claude\claude_desktop_config.json；所有版本均可通过“Settings → Developer → Edit Config”打开该文件：

{
  "mcpServers": {
    "goodreads": {
      "command": "/path/to/goodreads-mcp/.venv/bin/goodreads-mcp"
    }
  }
}

或者，在开发时运行 mcp dev goodreads_mcp/server.py，即可打开 Inspector UI 来试用各个工具。

首次运行验证

这些端点并非官方端点，因此请按以下顺序验证：

1. search_books("project hail mary") — 应该能直接正常工作
2. get_book("54493401") — 确认 .xml/WAF 变通方案有效；检查直方图是否已填充
3. get_reviews("54493401") — 应该会返回真实的评论文本
4. get_shelf("to-read") — 检查你的 user_id + RSS
5. list_shelves() — 尽力抓取书架名称

有关串联这些工具的端到端示例，请参阅 prompts/research-a-book.md。

测试

.venv/bin/pip install -e ".[test]"     # pytest + pytest-cov
.venv/bin/pytest                       # offline parser/unit tests
GOODREADS_LIVE=1 .venv/bin/pytest      # + live network smoke tests

离线测试套件使用固定数据运行；CI 使用 pytest-cov 运行该套件，并强制要求达到最低覆盖率（在 ci.yml 中设置 --cov-fail-under）。实时冒烟测试位于 tests/e2e/test_smoke_live.py，只有设置了 GOODREADS_LIVE=1 才会运行。每夜合规检查 每晚都会针对真实端点运行实时测试套件，因此上游变更会在一天内显现。

文档

• docs/design.md — 设计说明：数据接口、WAF 和登录处理、礼貌请求与并发
• docs/roadmap.md — 尚未实现的构想
• docs/maintenance.md — 本仓库的维护方式（Hive、ACMM L6、等待人工审核的外联 PR）
• docs/ai-ops-runbook.md — 每种自动化信号需要检查和执行的事项
• docs/quality.md — 测试和数据能够及不能够证明的内容
• docs/risk-tiers.md — 每个拉取请求都需要声明的风险等级
• docs/review-rubric.md — 审核清单
• docs/metrics.md — 成效指标
• docs/strategy.md — 项目的目标、不涉及的事项，以及用于判断项目是否按计划推进的命令
• docs/reflections/ — 关于此代码库的经验总结
• docs/SECURITY-AI.md — AI Agent 可以和不可以触及的内容

关于此项目

说明

此分支的开发工作借助了 AI，应谨慎对待。

这是一个第三方工具。它不是 Goodreads 或 Amazon 的官方产品，也未得到任何一方认可，并且不使用官方 API——自 2020 年 12 月以来就没有官方 API。“Goodreads”是其所有者的商标，此处仅用于说明本软件连接的对象。

它仅读取公开数据：不登录、不使用 Cookie、不写入数据。本软件按原样提供，不保证所依赖的端点会持续可用，也不保证使用本软件符合 Goodreads 的条款。请控制请求量。维护者不对使用本软件导致的限流、封禁、数据丢失或其他后果负责。

许可证

此分支根据 GNU 通用公共许可证 v3.0 授权，仅限第 3 版（GPL-3.0-only）——不会自动升级到后续版本。

其中包含来自 shreeyachand/goodreads-mcp 的代码，版权所有 (c) 2026 Shreeya Chand，根据 MIT 许可证发布。该代码仍受 MIT 许可证约束；根据 MIT 许可证的要求，其许可证文本和版权声明保留在 LICENSE.MIT 中。组合后的作品——上游代码及此分支的更改——根据 GPL-3.0 分发。