Goodreads MCP

📚 goodreads-mcp

ありがとうございます、Shreeya Chand。 このプロジェクトは shreeyachand/goodreads-mcp のフォークであり、この成果なくして存在し得ませんでした。終了したAPIを使わずにGoodreadsへアクセスするという中核的なアイデアと、このサーバーが提供するツール群は、Shreeyaのプロジェクトに由来します。心より感謝します。また、その成果を基に開発することを可能にしてくれたMITライセンスにも感謝します。このサーバーが役に立ったら、ぜひオリジナルのリポジトリにスターを付けてください。

Goodreads向けの読み取り専用MCP サーバーです。2020年12月以降、Goodreads APIが存在しないため、APIを使わずに構築されています。LLMが書籍、評価、レビューを検索・調査できます。ツールは、RSSフィード、JSONオートコンプリートエンドポイント、書籍ページに埋め込まれた__NEXT_DATA__データ、そしてGoodreadsのウェブサイト自体が使用するAppSync GraphQLバックエンドを利用します。ログインもCookieも書き込みもなく、公開データのみを扱います。

ツール

ツール	ソース／返される内容
search_books	JSON オートコンプリートエンドポイント（安定）— book_id、タイトル、著者、評価、表紙。max_results のデフォルトは 10 ですが、エンドポイントが返す一致候補は最大で約 5 件です
get_book	.xml ページ経由の __NEXT_DATA__（安定）— 詳細、表紙、評価のヒストグラム、すべてのシリーズへの所属、レビュー言語の内訳（review_language_limit はデフォルト 5、最大 25）。版の publication_date と作品の first_published、original_title、language、isbn／isbn13／asin、author_url（存在しない場合はそれぞれ null）
get_reviews	GraphQL — ページ分割された読者レビュー（本文、評価、いいね数、日付、ネタバレフラグ、パーマリンク）。limit のデフォルトは 10、上限は 100。サーバー側の min_rating／max_rating（1～5、min ≤ max）、sort（デフォルトは relevance、newest、oldest）、language（2 文字のコード。get_book の review_languages と同じ）、レビュー本文を対象にした search に対応。exclude_spoilers に対応し、has_more を返します
similar_books	GraphQL — ページ分割された「この本を読んだ人はこんな本も読んでいます」のおすすめ。limit は最大 100
author_books	GraphQL — その著者の任意の著書から取得する、人気順に並んだページ分割済みの著書目録と author_url。limit は最大 100
series_books	GraphQL — 読書順の位置を含む、ページ分割されたシリーズ作品。series_index（get_book の series_memberships の順序で 0 から始まるインデックス）でシリーズを指定します。limit は最大 100
get_editions	GraphQL — ページ分割された各版（形式、ISBN、出版社、publication_date としての出版日 YYYY-MM-DD、およびエポックミリ秒単位の生の publication_time）。limit は最大 100
book_lists	GraphQL — 本が掲載されている、ページ分割された Listopia リスト（タイトル、投票数、規模）。limit は最大 100
popular_books	リリースの year、または単一の month（1～12）で絞り込んだ、人気順の本。limit の上限は 50
compare_books	各 ID に対する get_book（.xml 経由の __NEXT_DATA__）— 評価と高評価／批判的評価の割合で、異なる本を 1～10 位に順位付けします。同じ ID が繰り返された場合は 1 回だけ取得します。ID が 10 件を超えると拒否されます。取得に失敗した本は error エントリとして返されます
get_shelf	棚の RSS フィード（安定）— 公開棚にある本（評価と年は整数、存在しない場合は None。日付は YYYY-MM-DD。さらに cover、pages、my_review）。page は 1 から始まり、1 ページあたり約 100 件です。user_id は設定済みのユーザーを上書きします。非公開プロフィールの場合は LoginRequired を送出します
list_shelves	公開プロフィールページをベストエフォートで HTML スクレイピング — 棚の名前。非公開プロフィールの場合は LoginRequired を送出します

すべてのツールには、MCP の読み取り専用アノテーション（読み取り専用、非破壊的、冪等）が登録されています。

探索ツールはすべて book_id を受け取り、book_id／タイトル／著者／評価／URL を含む結果を返すため、エージェントはツールを連続して呼び出せます。たとえば、similar_books → おすすめされた本に対する get_reviews のように使えます。book_id は入力側と出力側のどちらでも文字列（"54493401"、または入力時のスラッグ形式 "54493401-title"）なので、ある結果からコピーした値をそのまま次の呼び出しで使用できます。すべてのツールで average_rating は数値（または null）なので、異なるツールの結果をまとめて並べ替えられます。これは、一般的なウェブ検索では構築できない、構造化された書籍グラフです。

ページ分割に対応した 5 つの探索ツール（similar_books、author_books、series_books、get_editions、book_lists）は 20 件ずつ取得し、合計 limit は最大 100 件まで指定できます。popular_books の limit は最大 50 件です。レスポンスには returned と has_more が含まれるため、過剰なトラフィックを発生させずに、大規模な検索も実用的に行えます。

WAF とログインに関する注意： Goodreads の書籍 HTML ページは現在、通常の HTTP クライアントでは解決できない AWS WAF の JavaScript チャレンジ（HTTP 202）の背後にあります。get_book は .xml サフィックス付きのページを経由してこの問題を回避するため、ブラウザーなしでも引き続き動作します。Goodreads が依存しているパスにも WAF を適用するようになった場合、クライアントは分かりにくい解析エラーではなく、明確なメッセージとともに WAFChallenge を発生させます。 レビュー一覧ページ（/review/list/{uid}）は 2026 年 9 月にログイン必須になりました。同じ理由で、クライアントはサインインへのリダイレクト時に LoginRequired を発生させます。また、list_shelves は公開プロフィールページを読み取ります。

インストール

pip を使う場合：

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

または、Claude Desktop バンドルでも使用されている uv を使う場合：

cd goodreads-mcp
uv sync
uv run goodreads-mcp

Python ≥ 3.11 が必要です。

日付で番号付けされた各リリースは、PyPI に goodreads-mcp-ai としても公開され（goodreads-mcp という名前は無関係な別プロジェクトが使用しています）、server.json に基づいて、公式の MCP レジストリ に io.github.Danathar/goodreads-mcp-ai として登録されています。この登録には uvx のランタイムヒントが含まれており、それに従うクライアントは uvx goodreads-mcp-ai を実行します。自分で実行することもできます。

設定（任意）

ログインや Cookie は不要です。すべて公開データです。唯一の設定項目は、棚ツールの既定値となる数値の user_id です。これは goodreads.com/user/show/<ID>-yourname の <ID> の部分です。各棚ツールの呼び出し時に user_id を渡すこともできます。

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

環境変数 GOODREADS_USER_ID はファイルの値より優先されます。読み取れない設定ファイル、正しい JSON ではないファイル、JSON オブジェクトではないファイル、または user_id が文字列でも整数でもないファイルは、stderr に警告を出して無視されます（12345678 のような数値単体は受け付けられ、文字列として使用されます。ブール値、浮動小数点数、リスト、オブジェクトは無視されます）。サーバーは引き続き起動します。

Claude Desktop の設定

バンドル。 各リリースには goodreads-mcp.mcpb が含まれています。リリースは、サーバー自体に変更があった場合に月次で公開され、日付で番号付けされます（2026.10.0、2026.10.1、2026.11.0）。旧番号方式での最後のリリースは 0.1.1 で、日付で番号付けされたリリースはすべてそれより新しいものです。リリースの作成方法については、CONTRIBUTING.md を参照してください。Claude Desktop で .mcpb を開いてインストールします。バンドルに依存関係は含まれません。マニフェストは uv run でサーバーを起動し、ホストは初回起動時に pyproject.toml から専用環境を解決します。そのため、Python ≥ 3.11 があれば、macOS、Windows、Linux のいずれでも同じバンドルを使用できます。バンドルの任意設定「Goodreads User ID」（user_config.goodreads_user_id）は、GOODREADS_USER_ID としてサーバーに渡されます。空欄の場合も空の値として渡され、サーバーは設定ファイルの値を使用します。

手動設定。 サーバーを claude_desktop_config.json に追加します。macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json にあります。どのバージョンでも、設定 → 開発者 → 設定を編集 を開くとファイルが表示されます。

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

開発時は、mcp dev goodreads_mcp/server.py を実行すると、各ツールを試せる Inspector UI が開きます。

初回実行時の確認

エンドポイントは非公式のため、次の順序で確認してください。

1. search_books("project hail mary") — 正常に動作するはずです
2. get_book("54493401") — .xml/WAF 回避策が機能していることを確認します。ヒストグラムにデータが表示されていることを確認してください
3. get_reviews("54493401") — 実際のレビュー本文が返されるはずです
4. get_shelf("to-read") — user_id と RSS を確認します
5. list_shelves() — ベストエフォートで棚名を取得します

ツールを連続して実行するエンドツーエンドの例については、prompts/research-a-book.md を参照してください。

テスト

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

オフラインのテストスイートはフィクスチャで実行されます。CI では pytest-cov を使って実行され、カバレッジの下限（ci.yml の --cov-fail-under）が適用されます。ライブのスモークテストは tests/e2e/test_smoke_live.py にあり、GOODREADS_LIVE=1 が設定されていない場合はスキップされます。毎晩のコンプライアンス実行では、毎晩、実際のエンドポイントに対してライブテストスイートを実行するため、上流の変更は1日以内に検出されます。

ドキュメント

• docs/design.md — 設計に関するメモ：データの取得元、WAF とログインの処理、リクエストの節度と並行処理
• docs/roadmap.md — まだ実装されていないアイデア
• docs/maintenance.md — このリポジトリのメンテナンス方法（Hive、ACMM L6、人によるレビュー待ちのアウトリーチ PR）
• docs/ai-ops-runbook.md — 自動シグナルごとに確認・実行すること
• docs/quality.md — テストや数値が証明することと、証明しないこと
• docs/risk-tiers.md — 各プルリクエストで申告するリスクレベル
• docs/review-rubric.md — レビューチェックリスト
• docs/metrics.md — 成果指標
• docs/strategy.md — プロジェクトの目的、実施しないこと、進捗状況を確認するコマンド
• docs/reflections/ — このコードベースから得た教訓
• docs/SECURITY-AI.md — AI エージェントが操作してよいものと、してはいけないもの

このプロジェクトについて

メモ

このフォークの開発には AI の支援を利用しているため、慎重に取り扱ってください。

これはサードパーティ製のツールです。Goodreads または Amazon の公式製品ではなく、どちらからも承認されていません。また、公式 API は使用していません。公式 API は2020年12月以降、存在していません。「Goodreads」は所有者の商標であり、このソフトウェアが接続する対象を示す目的でのみ使用しています。

公開データのみを読み取ります。ログイン、Cookie、書き込みは行いません。本ソフトウェアは現状のまま提供されており、依存するエンドポイントが今後も動作することや、使用方法が Goodreads の利用規約に適合することを保証するものではありません。リクエスト数は控えめにしてください。本ソフトウェアの使用によるレート制限、ブロック、データ損失、その他の結果について、メンテナーは責任を負いません。

ライセンス

このフォークは GNU General Public License v3.0 のバージョン3のみ（GPL-3.0-only）に基づいてライセンスされています。後続バージョンへの自動アップグレードはありません。

shreeyachand/goodreads-mcp のコードを取り込んでいます。このコードの著作権は Copyright (c) 2026 Shreeya Chand に帰属し、MIT License のもとで公開されています。このコードは引き続き MIT License のもとにあり、MIT License の要件に従い、ライセンス文と著作権表示は LICENSE.MIT に保持されています。上流のコードとこのフォークによる変更を合わせた成果物は、GPL-3.0 のもとで配布されます。