shreeyachand/goodreads-mcp

API development

이 페이지는 AI로 자동 번역되었습니다. 기술적인 세부 사항은 원문을 확인하세요. 원문 보기

6 stars 4 forks 품질 78 트렌드 28MIT

Repository Install

a (local) mcp server to interface with Goodreads

개요

A 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 blob embedded in book pages. No login, no cookies, no writes — public data only. 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. GraphQL discovery tools page in batches of 20 and accept a total limit up to 100. Responses include returned and has_more, keeping larger lookups useful without allowing unbounded traffic. 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.

README

원문 README의 일부입니다. 원문 보기.

📚 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, cover, ratings histogram, all series memberships, 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 — paginated “readers also enjoyed” recommendations
`author_books`	GraphQL — paginated author bibliography (from any of their books)
`series_books`	GraphQL — paginated series books with reading-order placement; selectable membership for books in multiple series
`get_editions`	GraphQL — paginated editions (format, ISBN, publisher, date)
`book_lists`	GraphQL — paginated 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_books → get_reviews on a recommendation. This is the structured book graph a general web search can’t assemble.

GraphQL discovery tools page in batches of 20 and accept a total limit up to 100. Responses include returned and has_more, keeping larger lookups useful without allowing unbounded traffic.

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.

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

GitHub에서 전체 README 보기

설치

This server does not publish a one-line install command.

Open the repository installation guide MCP 초보자라면? mcpskill.org 가이드부터 시작하세요 →

설정

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