goodreads-mcp
This server provides read-only access to Goodreads book data without requiring an official API or login, enabling an LLM to research books, ratings, reviews, and related information.
Search books (
search_books) — Search by title, author, or ISBN; returns book ID, title, author, rating info, and cover URL.Get full book details (
get_book) — Retrieve comprehensive info including ratings histogram, series/position, and review-language breakdown.Fetch reader reviews (
get_reviews) — Paginated review text (up to 100) via GraphQL, with min/max star rating filters and spoiler exclusion.Discover similar books (
similar_books) — Get "Readers also enjoyed" recommendations (up to 40 results).Browse an author's bibliography (
author_books) — List all works by a book's primary author, ranked by popularity.Explore a book series (
series_books) — List all books in a series with reading-order placement (e.g., prequels marked as '0.5').Find book editions (
get_editions) — List published editions with format, ISBN, publisher, and publication date.View public shelves (
get_shelf) — Retrieve books from a user's public shelf (e.g., 'read', 'to-read', 'currently-reading') with pagination.List shelf names (
list_shelves) — List all public shelf names for a given Goodreads user.Compare books (
compare_books) — Rank multiple books by rating, including positive/critical review share breakdowns.Browse popular books (
popular_books) — Get the most popular books by release year or year + month.Explore Listopia lists (
book_lists) — Find lists a book appears on, with title, vote count, and size.
All results carry consistent fields (book ID, title, author, rating, URL), enabling easy chaining between tools.
Provides tools for searching books, retrieving book details (ratings, histogram, series, review languages), fetching paginated reader reviews with filters, finding similar books, author bibliographies, series books with reading order, published editions, and accessing public shelves — all from Goodreads public data.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@goodreads-mcpsearch for 'Project Hail Mary'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
📚 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 |
| stable (JSON endpoint) |
| stable ( |
| GraphQL — paginated reader reviews (text, rating, likes, date, spoiler flag, permalink) with server-side |
| GraphQL — "readers also enjoyed" recommendations |
| GraphQL — an author's bibliography (from any of their books) |
| GraphQL — books in a series with reading-order placement |
| GraphQL — published editions (format, ISBN, publisher, date) |
| GraphQL — Listopia lists a book appears on (title, votes, size) |
| GraphQL — most popular books by release year (or year+month), ranked |
| takes several book ids, ranks them by rating with positive/critical share |
| stable (RSS) — public 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_books → get_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_bookroutes 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 raisesWAFChallengewith 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" }
EOFEnv 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:
search_books("project hail mary")— should just workget_book("54493401")— confirms the.xml/WAF workaround; check the histogram is populatedget_reviews("54493401")— should return real review textget_shelf("to-read")— checks youruser_id+ RSSlist_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 testsdesign notes
Request-first, no browser automation. Everything is
httpxagainst JSON/RSS/embedded-JSON/GraphQL surfaces; the only HTML regex is inlist_shelvesand the GraphQL config discovery.GraphQL backbone (reviews).
get_reviewscalls 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 backnullrather than failing the call.WAF-aware. Book pages sit behind an AWS WAF JS challenge;
get_bookuses the.xmlpath that isn't gated, and the client raisesWAFChallengeif 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_reviewscaps 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 data —
get_booknow includes the ratings histogram, series/position, and review-language breakdown;series_booksandsimilar_bookscover series and recommendations;get_reviewsreturns paginated, filterable reader reviews.author bibliography —
author_booksreturns 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_bookslinks 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 toolsauthor_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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| book_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| book_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.).
| Name | Required | Description | Default |
|---|---|---|---|
| book_ids | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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'.
| Name | Required | Description | Default |
|---|---|---|---|
| book_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| book_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| book_id | Yes | ||
| max_rating | No | ||
| min_rating | No | ||
| exclude_spoilers | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| shelf | No | to-read | |
| user_id | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
popular_booksA
Most popular books by release date — Goodreads' "Popular by date" chart.
Ranks the books/works released in a given year (or a specific month of a year) by how many Goodreads members have added them. Mirrors the goodreads.com/book/popular_by_date/[/] page.
year: 4-digit release year. month: optional 1-12 for a single month; omit for the whole year. limit: how many to return (capped at 50).
Each entry has rank, count (members who added it), and the usual book_id/title/author/rating/url so you can chain into get_book/get_reviews.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| limit | No | ||
| month | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral transparency. It discloses that results are ranked by member additions, that each entry includes rank, count, book_id, title, author, rating, and url, and that the limit is capped at 50. It does not mention potential errors or authentication requirements, but it provides a solid overview of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence followed by parameter explanations. It is concise without unnecessary fluff, though it could be slightly tighter by combining the parameter notes into a single sentence. Overall, it is easy to read and understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough context for an agent to use the tool effectively: it mentions the output fields (rank, count, book_id, etc.) and hints at chaining to get_book/get_reviews. While it does not fully enumerate all possible response fields or error cases, given the simplicity of the tool, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning to each parameter beyond the schema: year is defined as a 4-digit release year, month is clarified as optional and ranges 1-12 (with omission meaning the whole year), and limit is described as how many to return with a cap at 50. This is a clear improvement over the bare type/default definitions in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it returns the most popular books for a given year or month, ranked by member additions. It specifies that it mirrors the Goodreads 'Popular by date' page, making the function unambiguous and distinct from siblings like author_books or search_books.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the input parameters but does not explicitly state when to use this tool over alternatives. It lacks phrases like 'use this when you need popular books by date' or 'not for searching by title.' While the function is implicit from the name and description, it does not offer explicit usage guidance or contrast with sibling tools.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| max_results | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| book_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| book_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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
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.
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.
9 tools is well-scoped for a book database client. It covers browsing, searching, details, reviews, shelves, series, and recommendations without being overwhelming.
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
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
MCP server for Russian books search, details, and recommendation candidates.
Read-only MCP server for verified book recommendations and reading lists.
MCP server for Project Gutenberg — 75,000+ public-domain ebooks with full plain-text retrieval.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP 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
- AlicenseNot gradedqualityDmaintenanceSelf-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.72MIT
- AlicenseAqualityBmaintenanceAn 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.41AGPL 3.0
- FlicenseAqualityCmaintenanceRead-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
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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