Skip to main content
Glama
shreeyachand

goodreads-mcp

by shreeyachand

📚 goodreads-mcp

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 RSS feeds, the JSON autocomplete endpoint, and the __NEXT_DATA__ blob embedded in book pages. No login, no cookies, no writes — public data only.

tools

tool

stability

search_books

stable (JSON endpoint)

get_book

stable (__NEXT_DATA__ via .xml path) — details, ratings histogram, series, review-language breakdown

get_reviews

GraphQL — paginated reader reviews (text, rating, likes, date, spoiler flag, permalink) with server-side min_rating / max_rating and exclude_spoilers; limit up to 100

similar_books

GraphQL — "readers also enjoyed" recommendations

author_books

GraphQL — an author's bibliography (from any of their books)

series_books

GraphQL — books in a series with reading-order placement

get_editions

GraphQL — published editions (format, ISBN, publisher, date)

book_lists

GraphQL — Listopia lists a book appears on (title, votes, size)

popular_books

GraphQL — most popular books by release year (or year+month), ranked

compare_books

takes several book ids, ranks them by rating with positive/critical share

get_shelf

stable (RSS) — public shelves

list_shelves

best effort (HTML) — public profiles

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_booksget_reviews on a recommendation. This is the structured book graph a general web search can't assemble.

WAF 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.

Related MCP server: anna-book-search

install

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

Requires Python ≥ 3.10.

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.

Claude Desktop config

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "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") — checks your user_id + RSS

  5. list_shelves() — best-effort shelf-name scrape

tests

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

design notes

  • Request-first, no browser automation. Everything is httpx against JSON/RSS/embedded-JSON/GraphQL surfaces; the only HTML regex is in list_shelves and the GraphQL config discovery.

  • GraphQL backbone (reviews). get_reviews calls Goodreads' AppSync GraphQL endpoint — the same backend the website uses. The web app ships a public read-only API key in its JS bundle; the client scrapes the endpoint + key from that bundle at runtime and caches them, so a key rotation self-heals (client.graphql_config). A hardcoded pair is kept as a fallback. This is what enables real pagination (past the ~30 reviews a page embeds) and server-side rating filters. GraphQL partial-success is respected: a deleted review's sub-resource just comes back null rather than failing the call.

  • WAF-aware. Book pages sit behind an AWS WAF JS challenge; get_book uses the .xml path that isn't gated, and the client raises WAFChallenge if it ever gets a challenge body so failures are loud, not silent. (The GraphQL endpoint is a separate AppSync host and isn't WAF-gated.)

  • Polite client. Single persistent session, browser-faithful headers, exponential backoff on 429/503; get_reviews caps paging at 100 reviews.

  • Caveats: all of this is unofficial and depends on markup/endpoints/keys that can drift.

shipped since v0.1

  • richer book dataget_book now includes the ratings histogram, series/position, and review-language breakdown; series_books and similar_books cover series and recommendations; get_reviews returns paginated, filterable reader reviews.

  • author bibliographyauthor_books returns an author's works (ranked by popularity) plus a link to their author page (author_url).

ideas for v2

  • author page detail (bio, photo, follower count) — not currently exposed cleanly: the author page is legacy server-rendered HTML with no structured JSON, and there's no discoverable GraphQL contributor-detail query, so this would require brittle DOM scraping. author_books links to the page instead.

  • caching layer for repeated lookups (the discovery tools each resolve the book first; a small TTL cache would cut duplicate GraphQL calls)

Available Tools

12 tools
author_booksA

List an author's works (bibliography), given any of their books.

Resolves the book's primary author, then returns their works ranked by popularity. Each result has book_id/title/author/rating/url. limit capped at 40.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
book_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses that it 'resolves the book's primary author', 'returns their works ranked by popularity', and 'limit capped at 40'. These are behavioral traits beyond the basic inputs and outputs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loaded with purpose, then details on resolution and ranking, then result fields and constraint. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and presence of output schema, the description covers input usage, resolution process, ranking, limit cap, and result fields. It lacks error handling details but is sufficient for a simple list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning beyond the schema: it explains that book_id is used to identify the author (via any of their books), and that limit is capped at 40. Although schema coverage is 0%, the description references both parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'author's works (bibliography)', and explains the input (any of their books). It distinguishes from sibling tools like get_book (single book) and search_books (general search) by focusing on author bibliography.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'given any of their books', indicating when to use this tool. It implies usage context (you have a book_id and want the author's other works) but does not directly mention when not to use or compare to all siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

book_listsA

List the Listopia lists a book appears on (e.g. "Best Dystopian Fiction"), ordered by popularity.

Each list has its title, total member votes, how many books it contains, and a 'url'. Good for "what kind of book is this / what's it grouped with" and for discovery. limit capped at 40.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
book_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full disclosure burden and largely succeeds: it reveals sorting behavior ('ordered by popularity'), return composition (title, total member votes, book count, url), and a hard constraint ('limit capped at 40'). It does not cover error behavior or auth needs, but for a simple read-oriented list tool these are minor omissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs with zero wasted words. The core purpose is front-loaded in the first sentence, and the second paragraph packs return fields, use cases, and the limit cap into three sentences — every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool with an output schema available, the description covers purpose, ordering, output shape, use cases, and the limit constraint. Since an output schema exists, return values needn't be spelled out further. The only notable gap is absence of sibling routing guidance, which is not critical given the clear scope statement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds real meaning for limit ('capped at 40') and implies book_id's role via 'a book appears on', but book_id is never explicitly documented and no format or edge-case behavior is given. Partial compensation rather than full.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'List the Listopia lists a book appears on', clarified by a concrete example ('Best Dystopian Fiction'). This clearly distinguishes the tool from siblings like similar_books, get_book, or get_shelf — an agent can tell at a glance what resource is being queried and how it differs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit use-case context: 'Good for "what kind of book is this / what's it grouped with" and for discovery.' This tells the agent when the tool is valuable, though it stops short of naming alternatives or stating when not to use it, e.g., versus similar_books.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compare_booksA

Compare several books side by side by rating and rating distribution.

Fetches each book and returns them ranked best-to-worst by average rating, with the ratings_histogram plus 'pct_positive' (share of 4-5 star) and 'pct_critical' (share of 1-2 star) so you can judge not just the average but how divisive each book is. Pass 2-10 book ids (from search_books etc.).

ParametersJSON Schema
NameRequiredDescriptionDefault
book_idsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With zero annotations, the description carries the full burden and delivers: discloses that books are fetched, ranked best-to-worst by average rating, and that derived metrics pct_positive and pct_critical are computed from ratings_histogram, including their semantic purpose (measuring divisiveness). This is exactly the non-obvious behavioral disclosure an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, opening with the core purpose and progressively adding derived-field semantics and input constraints. Each sentence earns its place, though the middle sentence is somewhat long and could be split for scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a rich output schema covering return values and low tool complexity (single param, no enums), the description provides sufficient completeness: ranking behavior, derived fields, and ID-source expectation are all addressed. Missing edge-case behavior (e.g., error on <2 or >10 IDs) is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must and does compensate: it states that book_ids should be 2-10 identifiers sourced from search_books and what they're used for. Loses one point for not stating the ID format (e.g., ISBN vs internal ID), though 'from search_books' mitigates ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Uses a specific verb ('Compare'), a specific resource ('books'), and a concrete criterion ('by rating and rating distribution'), clearly distinguishing batch comparison from single-item siblings like get_book and get_reviews without naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for when to use: 'Pass 2-10 book ids (from search_books etc.)', establishing both the expected input source and cardinality constraint. Stops short of explicit when-not-to-use or named alternative conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_bookA

Get full details for a book by its Goodreads id (numeric, or numeric-slug like '11870085-the-fault-in-our-stars').

Parses the page's embedded NEXT_DATA JSON (Apollo state) rather than scraping the DOM, which survives markup changes. Includes the full ratings histogram, series/position, and review-language breakdown — use get_reviews for the actual review text.

When you cite details or ratings from this book, link to its 'url'.

ParametersJSON Schema
NameRequiredDescriptionDefault
book_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully covers behavioral traits: it discloses the parsing method (embedded JSON vs DOM scraping), lists included data (ratings histogram, series/position, review-language breakdown) and excluded data (review text), and advises linking to the 'url' when citing details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences, each adding value: purpose and input format, implementation detail and content scope, and citation guidance. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description adequately covers what to expect. It mentions key data included and explicitly excludes review text, directing to a sibling tool. It also provides citation advice, making it complete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only provides a 'book_id' string parameter with no description. The description adds meaning by explaining it accepts numeric IDs or numeric-slug formats, which is essential for correct use.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get full details for a book by its Goodreads id', specifying the verb and resource. It distinguishes from siblings like get_reviews by noting that it includes ratings histogram, series info, and review-language breakdown, but not review text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (to get full details including ratings, series, etc.) and explicitly mentions an alternative (get_reviews for review text). It does not explicitly state when not to use it, but the guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_editionsA

List published editions of a book (formats, ISBNs, publishers, dates).

Useful for "which edition / format / ISBN" questions. limit capped at 40.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
book_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It only discloses a limit cap of 40, but fails to mention pagination, ordering, behavior for invalid book_id, or any side effects. This is insufficient for a read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no wasted words. First sentence states purpose, second adds usage context and a behavioral note. It is efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values are covered. However, parameter coverage is incomplete, and behavioral details are sparse. For a list tool, pagination and error handling are missing, making it barely adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It describes the limit parameter's cap (40) but not the required book_id parameter. This adds some value but leaves the main parameter unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists published editions of a book, specifying formats, ISBNs, publishers, and dates. It distinguishes from siblings like get_book (which retrieves a single book) or search_books (which searches for books).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions it is useful for questions about 'which edition / format / ISBN,' providing clear context for when to use it. However, it lacks explicit when-not to use or alternatives, and does not cover exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_reviewsA

Get reader reviews for a book — the actual review text, not just a score.

Fetches from Goodreads' GraphQL backend with true pagination, so limit can exceed the ~30 shown on a page. Reviews come in "most relevant" order and aggregate across all editions of the work. Each review has the reviewer name, star rating (1-5), full text, like/comment counts, date, a spoiler flag, a 'url' permalink (use it to cite/link), and the reviewer's profile url.

limit: max reviews to return (capped at 100 to stay polite). min_rating / max_rating: server-side star filters, e.g. min_rating=4 for positive reviews, max_rating=2 for the critical ones. exclude_spoilers: drop reviews flagged as spoilers.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
book_idYes
max_ratingNo
min_ratingNo
exclude_spoilersNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses review order ('most relevant'), aggregation across editions, limit cap at 100, and server-side filtering. Lists each field returned (reviewer name, rating, text, etc.), making behavior fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise yet informative: opening sentence states purpose, followed by paragraph on behavior and returned data, then parameter explanations. No wasted words, well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers tool purpose, data source, return fields, parameter effects, constraints. With 5 parameters and an output schema, the description provides sufficient context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage. Description adds meaning for each parameter: limit (capped at 100, true pagination), min_rating/max_rating (server-side star filters), exclude_spoilers (drops flagged spoilers). book_id is implicitly clear. Adds substantial value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool gets reader reviews for a book, emphasizing actual text versus score. Distinguishes from siblings like 'get_book' or 'get_shelf' by focusing on reviews.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context on data source (Goodreads GraphQL), pagination, ordering, and aggregation across editions. Implicitly indicates when to use (getting reviews) but lacks explicit 'when not to use' or comparison with siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_shelfA

List books on a shelf via its RSS feed (public shelves; no auth).

Common shelves: 'read', 'currently-reading', 'to-read', plus any custom shelf name. RSS pages hold ~100 items; pass page=2,3,... for more. Defaults to the configured GOODREADS_USER_ID.

When you cite a book from a shelf, link it to its 'link' field.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
shelfNoto-read
user_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses public nature, no auth required, RSS feed behavior, ~100 items per page, default user ID, and a citation note. Missing potential error cases or rate limits, but covers essential behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Five sentences, each purposeful. Front-loaded with purpose, then specific details. No redundancy or filler. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (not shown but indicated), the description doesn't need to document return values. It covers all key aspects: purpose, parameters, behavior, and a usage note. Complete for a simple list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description adds meaning for all three parameters: shelf (common examples, default), page (pagination, default), user_id (defaults to configured ID). Fully compensates for schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it lists books on a shelf via RSS feed, noting it's for public shelves. While it mentions common shelves, it doesn't explicitly differentiate from sibling tools like similar_books or list_shelves, but the focus on RSS feed and shelf-specific listing is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on when to use (list books on a shelf) and basic usage (public, no auth, pagination). However, it lacks explicit when-not-to-use or alternatives among siblings, leaving the agent to infer from context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_shelvesA

List a user's shelf names (scraped from their review-list page; best effort). Defaults to the configured user.

ParametersJSON Schema
NameRequiredDescriptionDefault
user_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses scraping source and best-effort nature, adding important context beyond a simple 'list shelves' statement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with front-loaded action, source, and default, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a simple list tool with output schema present; no missing information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds meaning to the optional user_id parameter by stating default behavior, compensating for 0% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool lists a user's shelf names with source and effort level, distinguishing it from sibling tools like get_shelf.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Specifies default behavior for user_id but does not explicitly state when to use vs alternatives or provide exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_booksA

Search Goodreads for books by title/author/ISBN.

Uses the JSON autocomplete endpoint (no auth, no HTML parsing). Returns book_id, title, author, rating info, and a cover URL.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
max_resultsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses no auth and no HTML parsing, which is useful. However, lacks information on rate limits, error handling, or pagination behavior, which would be important for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three efficient sentences, each serving a purpose: purpose, technical detail, return info. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the tool's function, technical approach, and return fields. With an output schema present, the return info may be redundant, but still adds completeness. Lacks only minor details like error behaviors.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage, so the description must compensate. It clarifies the query parameter accepts title/author/ISBN, but doesn't explain max_results semantics beyond its default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states searching Goodreads for books by title/author/ISBN, which differentiates it from siblings like author_books or get_book. However, it doesn't explicitly call out the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for broad book searches, but provides no when-to-use vs alternatives or exclusions. The technical detail about JSON endpoint is helpful but not enough for usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

series_booksA

List the books in a series (with reading-order placement), given any book in that series.

Each entry has the series 'placement' (e.g. '1', '0.5' for a prequel), 'is_primary' (a main-sequence entry vs companion), and the usual book_id/title/author/rating/url. limit capped at 40.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
book_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries the full burden. It discloses that the tool returns placement, is_primary, and book details, and that limit is capped at 40. However, it does not mention error handling, authentication needs, or what happens if the book is not in a series.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first establishes purpose, second adds detail on output and constraint. Every sentence is necessary and efficient, no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a simple list tool with 2 params and no annotations, the description covers key aspects: input requirement, output fields, and a constraint. Minor gaps include lack of error info and explicit mention that the book must belong to a series, but overall it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description adds value by explaining book_id as 'given any book in that series' and stating limit cap at 40 with default 20. However, it does not specify format, validation, or constraints for book_id, leaving some ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'List the books in a series (with reading-order placement)', using specific verb and resource. Uniquely identifies the tool's function among siblings like author_books and get_book.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage by providing any book in the series, and mentions limit cap of 40. Lacks explicit when-to-use or when-not-to-use guidance, but context is sufficient for an informed agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

similar_booksA

"Readers also enjoyed" — books similar to the given one.

Goodreads' own recommendation graph (hard to reproduce with web search). Each result has book_id/title/author/rating/url so you can chain into get_book or get_reviews. limit capped at 40.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
book_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses output fields (book_id, title, author, rating, url) and a behavioral constraint ('limit capped at 40'), which adds transparency beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: three short sentences front-load the purpose, include key behavioral details, and avoid any unnecessary text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple recommendation tool with output schema existing, the description covers purpose, output fields, chaining opportunities, and a constraint; could mention sorting or pagination but is sufficient for usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate; it indirectly explains limit with 'capped at 40' and implies book_id is 'the given one', but does not detail book_id format or limit defaults beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'books similar to the given one' and references Goodreads' recommendation graph, distinguishing it from sibling tools like search_books or author_books.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context that the recommendation is 'hard to reproduce with web search' and notes that results can be chained into get_book or get_reviews, offering implicit guidance on when to use; lacks explicit when-not usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

A4.1/5.0
Disambiguation5/5

Each tool targets a distinct resource or action: author's works, book details, editions, reviews, shelf, shelves list, search, series, and similar books. There is no overlap in purpose.

Naming Consistency3/5

Names mix patterns: 'get_' (get_book, get_editions, get_reviews, get_shelf), 'list_' (list_shelves), 'search_' (search_books), and noun phrases without verbs (author_books, series_books, similar_books). While all are understandable, the inconsistency could confuse an agent.

Tool Count5/5

9 tools is well-scoped for a book database client. It covers browsing, searching, details, reviews, shelves, series, and recommendations without being overwhelming.

Completeness4/5

Covers most core interactions: search, details, reviews, editions, author bibliography, series, shelves, and recommendations. Minor gaps like author bio or quotes are acceptable for a focused tool set.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    MCP server that provides book recommendation tools, allowing an AI agent to search and filter books by genre, page count, and ratings using the Goodreads dataset.
    1
  • A
    license
    Not graded
    quality
    D
    maintenance
    Self-hosted MCP server for searching and discovering books using Anna's Archive and Goodreads datasets, enabling full-text search, ISBN/md5 lookup, similarity matching, and optional download URL retrieval.
    7
    2
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    An MCP server that lets an LLM browse, search, and download books from OPDS catalogs (e.g., Project Gutenberg, Standard Ebooks) using tools for feed navigation, full-text search, and acquisition link downloads.
    4
    1
    AGPL 3.0
  • F
    license
    A
    quality
    C
    maintenance
    Read-only MCP server that provides tools to search books, get book details, list authors, and view library statistics from a PostgreSQL database.
    5

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/shreeyachand/goodreads-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server