📚 goodreads-mcp

Thank you, Shreeya Chand. This project is a fork of shreeyachand/goodreads-mcp, and it would not exist without that work. The core idea of reaching Goodreads without its retired API, and the tool set this server offers, come from Shreeya's project. We're grateful for it, and for the MIT licence that let us build on it. If this server is useful to you, please go star the original.

A read-only MCP server for Goodreads — built without the Goodreads API, because there hasn't been one since December 2020. Lets an LLM find and research books, ratings, and reviews. Tools ride on the JSON autocomplete endpoint, the __NEXT_DATA__ blob embedded in book pages, the AppSync GraphQL backend the Goodreads website itself uses, and the shelf RSS feed, which Goodreads has answered with 404 for every user since Oct 2026. No login, no cookies, no writes — public data only.

tools

Every tool is registered with MCP read-only annotations (read-only, non-destructive, idempotent).

The discovery tools all take a book_id and return results carrying book_id/title/author/rating/url, so an agent can chain them — e.g. similar_books → get_reviews on a recommendation. book_id is a string on both sides ("54493401", or the slug form "54493401-title" on input), so a value copied out of one result is accepted as-is by the next call. average_rating is a number (or null) in every tool, so results from different tools sort together. This is the structured book graph a general web search can't assemble.

The five paginated discovery tools (similar_books, author_books, series_books, get_editions, book_lists) page in batches of 20 and accept a total limit up to 100; popular_books caps limit at 50. Responses include returned and has_more, keeping larger lookups useful without allowing unbounded traffic.

WAF and login note: Goodreads book HTML pages now sit behind an AWS WAF JavaScript challenge (HTTP 202) that plain HTTP clients can't solve. get_book routes around it via the .xml-suffixed page, so it still works without a browser. If Goodreads ever extends the WAF to a path we depend on, the client raises WAFChallenge with a clear message instead of a confusing parse error. The review-list page (/review/list/{uid}) became login-only in Sep 2026; the client raises LoginRequired on a sign-in redirect for the same reason, and list_shelves reads the public profile page instead.

install

With pip:

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

Or with uv, which is also what the Claude Desktop bundle uses:

cd goodreads-mcp
uv sync
uv run goodreads-mcp

Requires Python ≥ 3.11.

Each date-numbered release is also published to PyPI as goodreads-mcp-ai (the goodreads-mcp name there belongs to an unrelated project) and listed on the official MCP registry as io.github.Danathar/goodreads-mcp-ai, from server.json. The listing carries a uvx runtime hint; a client that follows it runs uvx goodreads-mcp-ai, which you can also run yourself.

config (optional)

No login or cookies — everything is public data. The only setting is your numeric user_id, the default for the shelf tools. It's the number in goodreads.com/user/show/<ID>-yourname; you can also pass user_id to each shelf tool per call.

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

Env var GOODREADS_USER_ID overrides the file. A config file that can't be read, isn't valid JSON, isn't a JSON object, or has a user_id that is neither a string nor a whole number is ignored with a warning on stderr (a bare number such as 12345678 is accepted and used as its string form; booleans, floats, lists and objects are ignored); the server still starts.

Claude Desktop config

Bundle. Each release carries a goodreads-mcp.mcpb. Releases come out monthly when the server itself changed, numbered by date (2026.10.0, 2026.10.1, 2026.11.0); 0.1.1 was the last of the old numbering, and every date-numbered release is newer than it. See CONTRIBUTING.md for how one is cut. Open the .mcpb in Claude Desktop to install. The bundle ships no dependencies — the manifest launches the server with uv run, and the host resolves pyproject.toml into a private environment on first launch — so one bundle runs on macOS, Windows and Linux with any Python ≥ 3.11. The bundle's optional "Goodreads User ID" setting (user_config.goodreads_user_id) is passed to the server as GOODREADS_USER_ID; left empty, it is passed as an empty value, and the server falls back to the config file.

Manual. Add the server to claude_desktop_config.json — on macOS ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows %APPDATA%\Claude\claude_desktop_config.json; in any version, Settings → Developer → Edit Config opens it:

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

Or for development, mcp dev goodreads_mcp/server.py gives you the Inspector UI to poke each tool.

first-run verification

The endpoints are unofficial, so verify in this order:

1. search_books("project hail mary") — should just work
2. get_book("54493401") — confirms the .xml/WAF workaround; check the histogram is populated
3. get_reviews("54493401") — should return real review text
4. get_shelf("to-read") — raises ShelfFeedUnavailable while Goodreads answers the shelf feed with 404 (since Oct 2026); that is not a user_id problem
5. list_shelves() — best-effort shelf-name scrape

For an end-to-end example that chains the tools, see prompts/research-a-book.md.

tests

.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

The offline suite runs on fixtures; CI runs it with pytest-cov and enforces a coverage floor (--cov-fail-under in ci.yml). The live smoke tests are in tests/e2e/test_smoke_live.py and skip unless GOODREADS_LIVE=1 is set. The nightly compliance run runs the live suite against the real endpoints every night, so upstream drift shows up within a day.

documentation

• docs/design.md — design notes: the data surfaces, WAF and login handling, politeness and concurrency
• docs/roadmap.md — ideas not built yet
• docs/maintenance.md — how this repository is maintained (Hive, ACMM L6, outreach PRs held for human review)
• docs/ai-ops-runbook.md — what to check and do for each automated signal
• docs/quality.md — what the tests and numbers do and do not prove
• docs/risk-tiers.md — the risk tier every pull request declares
• docs/review-rubric.md — the review checklist
• docs/metrics.md — outcome metrics
• docs/strategy.md — what the project is for, what it won't do, and the commands that say whether it is on track
• docs/reflections/ — lessons learned about this codebase
• docs/SECURITY-AI.md — what AI agents may and may not touch

about this project

license

This fork is licensed under the GNU General Public License v3.0, version 3 only (GPL-3.0-only) — no automatic upgrade to later versions.

It incorporates code from shreeyachand/goodreads-mcp, Copyright (c) 2026 Shreeya Chand, released under the MIT License. That code remains under MIT; its licence text and copyright notice are preserved in LICENSE.MIT as the MIT licence requires. The combined work — upstream code together with this fork's changes — is distributed under GPL-3.0.