openlibrary-mcp-server

---

概要

Open Library のカタログには、2,000 万冊以上の書籍、版、著者、件名が収録されており、Internet Archive のスキャン済み書籍の全文検索にも対応しています。検索や閲覧のほか、作品から版へ、著者から著作へと掘り下げて調べたり、表紙画像の URL を作成したりできます。

ツール

ツール	説明
openlibrary_search_books	フィールドフィルター（タイトル、著者、主題、出版社、ISBN、言語）を使ったカタログ検索。プロバイダーが選択した版、ページネーション、任意のリアルタイム閲覧可否情報に対応します
openlibrary_get_work	Open Library Work ID（OL…W）で著作を取得します — タイトル、説明、主題、表紙 ID、著者 ID
openlibrary_get_editions	著作の各版を一覧表示します — 出版社、言語、形式、ISBN、印刷部数の詳細
openlibrary_get_edition	ISBN-10、ISBN-13、OCLC、LCCN、Open Library Edition ID（OL…M）を使い、1 回の呼び出しで最大 50 個の異なる識別子を解決します。見つからなかった識別子と未処理の識別子も報告します
openlibrary_search_authors	著者名で検索します — 著者 ID、生没年月日、代表作、主題との関連情報を返します
openlibrary_get_author	Open Library Author ID（OL…A）で著者の詳細を取得します — 略歴、年月日、写真 ID、Wikidata、VIAF、ISNI、Goodreads、LibraryThing のリンク済み識別子
openlibrary_get_author_works	著者の著作を一覧表示します — タイトル、表紙 ID、版や詳細をさらに調べるための Work OLID
openlibrary_get_subject	主題タグで著作を閲覧します — 該当する著作と版数、表紙 ID、および著作の総数を返します
openlibrary_search_inside	Internet Archive の書籍のスキャン済みテキストを全文検索します — 該当する項目と抜粋を返します
openlibrary_get_cover_url	書籍の表紙画像または著者の写真の URL を S/M/L サイズで解決します — Markdown に埋め込める直接の HTTPS URL を返します

リソース

リソース	説明
openlibrary://works/{work_id}	Open Library Work ID による著作の詳細 — タイトル、説明、主題、表紙 ID、著者 ID を注入可能なコンテキストとして提供します
openlibrary://authors/{author_id}	Open Library Author ID による著者の詳細 — 名前、略歴、年月日、写真 ID、リンク済み外部識別子を注入可能なコンテキストとして提供します

どちらのリソースも、openlibrary_get_work と openlibrary_get_author で利用できるデータと同じものを提供します — MCP リソースを表示しないクライアントに便利です。

エージェントスキル

openlibrary-guide では、版の選択、書誌情報の解決、箇所の特定、不完全なメタデータを扱います。npm、Docker、デスクトップ用の各バンドルに含まれており、MCP スキルの検出と skill:// リソースを通じて提供されます。

機能リファレンス

ページネーションに対応するツールは、1 回の呼び出しにつき最大 100 行を返します。100 を超える正の整数の上限値は、適用された上限値と次のオフセットを示す通知とともに制限されます。OPENLIBRARY_CLAMP_LIMITS=false にすると、100 を超える値に対するスキーマ検証エラーが再び有効になります。テキスト出力と構造化出力には、配列や数値精度を含め、同じ完全なドメインデータが含まれます。

openlibrary_search_books _ツール

• Solr のフィールドプレフィックス（title:、author:、subject:、publisher:、isbn:、language:）または専用のフィルターパラメーターを使ったフリーテキストクエリ。1 ページあたり 1～100 件（デフォルトは 10 件）、オフセットによるページネーション
• sort：relevance（デフォルト）、new、old、rating、editions
• language には 3 文字の MARC コード、または変換可能な 2 文字の ISO コードを指定できます。変換できない 2 文字コードは、無視されず unknown_language_code として失敗します
• include_availability を指定すると、Internet Archive の貸出・閲覧可否のリアルタイム情報が追加されます（遅延は約 200 ミリ秒）。デフォルトでは無効です。Open Library が返さないフラグは false として報告せず、省略されます。また、availability: null は、その著作について何も返されなかったことを意味します
• 版数、表紙 ID、主題、Internet Archive 識別子を含む著作レベルのレコードを返します
• 任意の matching_edition と matching_edition_count により、Search API が選択した版と一致件数が保持されます。選択される版はプロバイダーの順位付けに基づくもので、フィールド指定のない検索語がすべてその版に一致することを証明するものではありません
• invalid_search_query は、上流からの HTTP 422 検証エラーを復旧方法の案内とともに報告します。具体的なフィルターを指定した空のクエリも引き続き使用できます

---

openlibrary_get_work _tool

• Open Library Work ID（OL…W）で取得します。/works/ を任意で前置できます。それ以外の値（ISBN、版、著者 OLID など）は入力検証でリクエスト前に失敗し、ISBN から作品を取得する方法として openlibrary_get_edition（id_type: "isbn"）を案内します
• タイトル、説明、主題（場所・時期・人物ごとの内訳を含む）、表紙 ID、著者 ID を返します。著者名は含まれません（openlibrary_get_author または openlibrary_search_books を使用してください）
• 統合された Work ID でも引き続き取得できます。リダイレクトチェーンをたどって正規レコードを取得し、work_id には正規 ID が示されます。両者が異なる場合は、エンリッチメント通知に両方の ID が記載されます
• Work ID が存在しない場合、またはリダイレクトチェーンの到達先に作品がない場合は not_found になります

---

openlibrary_get_editions _tool

• Work ID（OL…W）で作品の版を一覧表示します。/works/ を任意で前置できます。1 ページあたり 1～100 件（デフォルトは 10 件）で、オフセット方式のページネーションに対応し、指定した offset が出力に含まれます
• openlibrary_get_work と同じ work_id 検証を行います。ISBN から作品を取得するには openlibrary_get_edition（id_type: "isbn"）を使用します
• ISBN-10/13、出版社、言語、ページ数、表紙 ID、版の OLID（OL…M）を返します。記録されている場合は physical_format と edition_name も返します
• 統合された Work ID でも引き続き取得できます。正規の作品の版が、その ID を work_id にして返され、エンリッチメント通知には両方の ID が記載されます。現存する作品の場合、リクエストは 1 回で済みます
• Work ID が存在しない場合、またはリダイレクトチェーンの到達先に作品がない場合は not_found になります

---

openlibrary_get_edition _tool

• 入力文字列を 1～1,000 件受け付け、完全一致する文字列を重複排除して、最初の 50 個の異なる識別子を 1 回の上流バッチで処理します。残りは再送信用に unprocessed として返されます。すべての識別子に共通の id_type を指定します。指定できる値は、isbn（10 桁または 13 桁。ISBN-10 はチェックディジットが X で終わる場合があります）、oclc（数字）、lccn（検証なし）、olid（OL…M）です。OPENLIBRARY_CLAMP_LIMITS=false の場合、入力配列は 50 件に制限されます
• 部分的な成功に対応しています。解決できた識別子はリクエスト順に editions に返され、それ以外は invalid_identifier（形式が不正で、上流に送信されなかった）または not_found（形式は正しいが、レコードがない）として unresolved に返されます。何も解決できなかった場合にのみ、呼び出しは失敗します
• Open Library のバッチ検索自体が失敗した場合は、再試行可能な upstream_unavailable になります。対象は、レート制限以外の HTTP エラーステータス、または HTML ページです。これにより、上流の障害が版の欠落として扱われることはありません
• 著者情報はインラインで含まれます。版独自の著者クレジット、または版に記載がない場合は親作品から取得した source: "work" の著者情報が含まれます。これらの検索に失敗してもバッチの結果は返され、著者情報が欠落している版、または ID で表示されている版はエンリッチメント通知に記載されます
• ISBN-10/13、OCLC、LCCN、LC 請求記号、カタログに記録されたすべての languages、ページ数、表紙 ID、親作品 ID、および存在する場合は Internet Archive の ebook_url を返します。単数形の language には、カタログに記録された最初の言語が引き続き設定されます。physical_format と edition_name は、存在する場合、カタログの表記をそのまま保持します
• 処理した識別子のいずれも解決できなかった場合、既存の型付きエラーにもすべての unprocessed 識別子がデータと復旧ヒントに含まれます

---

openlibrary_search_authors _tool

• 名前で検索します。部分一致や別名にも一致します。1 ページあたり 1～100 件（デフォルトは 10 件）で、オフセット方式のページネーションに対応します
• 著者 ID（OL…A）、別名、生没年月日、代表作、作品数、主な主題、平均評価を返します

openlibrary_get_author _ツール

• 著者 ID（OL…A）で取得します。先頭の /authors/ プレフィックスは削除されます
• 経歴、生年月日・没年月日、写真 ID、関連識別子（Wikidata、VIAF、ISNI、Goodreads、LibraryThing）を返します
• 統合された著者 ID からも引き続きアクセスできます。応答は正規レコードであり、要求された ID と異なる場合は、エンリッチメント通知に正規 ID が記載されます
• 著者 ID が存在しない場合、著者以外のレコード（作品または版の OLID）を示す場合、またはリダイレクトチェーンの到達先に著者がいない場合は、not_found を返します

---

openlibrary_get_author_works _ツール

• 著者 ID（OL…A）に紐づく作品を一覧表示します。1 ページあたり 1～100 件（デフォルトは 20 件）で、オフセットページネーションを使用し、指定した offset も出力に含まれます
• 各作品のタイトル、初版発行日、表紙 ID、作品 ID（OL…W）を返します
• 統合された著者 ID からも引き続きアクセスできます。要求された ID と異なる場合は、エンリッチメント通知に正規 ID が記載されます
• 著者 ID が存在しない場合、著者以外のレコード（作品または版の OLID）を示す場合、またはリダイレクトチェーンの到達先に著者がいない場合は、not_found を返します

---

openlibrary_get_subject _ツール

• 件名は前後の空白を削除して小文字に変換し、空白をアンダースコアに正規化します。1 ページあたり 1～100 件（デフォルトは 12 件）で、オフセットページネーションを使用し、指定した offset も出力に含まれます
• 入力が空白の場合、リクエストを送信する前に invalid_subject として失敗します
• 正規の件名、正規化された件名キー、作品の総数に加え、各作品の著者名、版数、表紙 ID を返します
• 結果が空の場合は、別の語形、類義語、またはより広い用語を試すよう促す復旧通知が含まれます。件名タグはユーザーが投稿するため、一貫性がありません

---

openlibrary_search_inside _ツール

• Internet Archive のスキャン済み書籍の全文を検索します。「この一節が掲載されている本はどれか」という問いに答えられる唯一のツールです。完全一致にはフレーズを引用符で囲み、引用符なしの用語は個別に照合されます
• ライブインデックスに対して通常 10～30 秒かかり、メタデータツールより大幅に時間がかかります。一般的な書籍検索ではなく、必要なときに意図的に使用してください
• 1 ページあたり 1～100 件（デフォルトは 10 件）で、オフセットページネーションを使用します。各結果には、同じ結果セット内でのみ比較できる関連度スコアが付与されます
• 結果のキーは Open Library の作品 ID ではなく、Internet Archive の ia_identifier です。カタログレコードを特定するには、openlibrary_search_books の ia_identifiers と照合してください
• インデックスから結果セットなしの応答があった場合は、再試行可能な upstream_unavailable を返します。検索失敗が「該当する本はない」と誤解されることはありません

---

openlibrary_get_cover_url _ツール

• id（数値）、isbn（10 桁または 13 桁。ISBN-10 はチェックディジットが X の場合があります）、または olid（target: "book" の場合は OL…M、target: "author" の場合は OL…A）から表紙または著者写真の URL を解決します。size は S／M／L（デフォルトは M）です
• リクエストを送信する前に識別子をローカルで検証します。パス区切り文字、..、制御文字が含まれる場合は invalid_identifier として失敗し、isbn による著者検索は invalid_target として失敗します
• このツールは URL を取得せずに生成します。URL が返されても、表紙の存在は確認されません
• 出力される URL は ![cover](url) としてそのまま埋め込めます

---

openlibrary://works/{work_id} _リソース

• 特定の本についての会話で利用できる application/json コンテキストとして、openlibrary_get_work と同じフィールドを返します
• work_id は openlibrary_search_books または openlibrary_get_author_works から取得します。統合済み ID は正規の作品に解決され、返される work_id にはその正規 ID が含まれます。作品ではない ID（版または著者の OLID）は見つかりません

---

openlibrary://authors/{author_id} _リソース

• 特定の著者についての会話で利用できる application/json コンテキストとして、openlibrary_get_author と同じフィールドを返します
• author_id は openlibrary_search_authors から取得します。統合済み ID は正規の著者に解決され、返される author_id にはその正規 ID が含まれます。著者ではない ID（作品または版の OLID）は見つかりません

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、切り替え可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレースに対応した構造化ログを備えています。

Open Library 固有の機能：

• Open Library の検索、全文検索、書籍、著者、件名の各 API、表紙 URL の構築、Internet Archive の利用可否の照会
• 作品からエディション、著者から作品への詳細検索。ツールの出力間で OLID を明示的に相互参照します
• Open Library のボットブロック規約に従い、サーバーを識別する User-Agent ヘッダーを設定可能（OPENLIBRARY_USER_AGENT）
• エディションの一括解決 — 1 回の上流呼び出しで最大 50 件の ISBN/OCLC/LCCN/OLID 識別子を処理し、識別子ごとに部分的な失敗を報告します
• エンドポイントの種類に応じたタイムアウト（レコード照会は 10 秒、検索は 30 秒、全文検索は 45 秒）を 50 秒の再試行予算内で設定しています。これにより、応答の遅い上流には十分な時間を与えつつ、障害のある上流は一般的な 60 秒のクライアントタイムアウトより前に分類済みエラーを返します。ゲートウェイエラーがループ内で再試行されることはありません

エージェントに適した出力：

• 結果が空の場合は必ず復旧のための案内を表示します — 検索条件を示し、クエリを広げる方法や再試行するオフセットを提案します
• 統合レコードの通知 — openlibrary_get_author、openlibrary_get_author_works、openlibrary_get_work、openlibrary_get_editions は統合先へリダイレクトされ、要求した ID が統合済みの場合は、補足通知で正規 ID を示します
• 項目ごとの部分的な失敗 — openlibrary_get_edition はバッチ全体を失敗させるのではなく、解決済みのエディションと型付きの unresolved 理由を返します
• 完全なテキスト出力と構造化出力の両方で、上限調整と復旧の通知を維持します

はじめに

ホストされているサーバーを Claude Code に追加します。API キーは不要です：

claude mcp add --transport http openlibrary-mcp-server https://openlibrary.caseyjhand.com/mcp

または、ローカルで実行します：

claude mcp add openlibrary-mcp-server -- npx -y @cyanheads/openlibrary-mcp-server

その他のクライアントでは、MCP 設定ファイルに次の内容を追加します：

{
  "mcpServers": {
    "openlibrary-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/openlibrary-mcp-server"]
    }
  }
}

Docker またはソースからのビルドについては、サーバーの実行を参照してください。

設定

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http	stdio
MCP_HTTP_PORT	HTTP サーバーのポート	3010
MCP_HTTP_ENDPOINT_PATH	MCP サーバーをマウントする HTTP エンドポイントのパス	/mcp
MCP_SESSION_MODE	HTTP セッションの動作モード：stateless、stateful、auto。src/index.ts で宣言された stateless を上書きします。	stateless
MCP_PUBLIC_URL	TLS を終端するリバースプロキシ環境で使用する公開オリジンの上書き値	なし
MCP_AUTH_MODE	認証：none、jwt、oauth	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）	info
MCP_GC_PRESSURE_INTERVAL_MS	オプトインの Bun 専用強制 GC 負荷ループ（ミリ秒）。ヒープの増加が見られる場合の開始値として 60000 を推奨します。	0（無効）
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OPENLIBRARY_USER_AGENT	すべての Open Library API リクエストで送信する User-Agent。コミュニティの慣例に従い、連絡先のメールアドレスを含めてください。	openlibrary-mcp-server [email protected]
OPENLIBRARY_CLAMP_LIMITS	ページの上限を 100 に制限し、重複のない最初の 50 件のエディション識別子を処理して、残りを返します。false にすると、行数 100 件、生の識別子 50 件という厳密な入力上限に戻ります。	true
OTEL_ENABLED	OpenTelemetry を有効にします	false

オプションの上書き設定の一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

Bun v1.4.0 以降、または Node.js ≥ 24.0.0 が必要です。

• クローンしてインストール：

  git clone https://github.com/cyanheads/openlibrary-mcp-server.git
  cd openlibrary-mcp-server && bun install
  cp .env.example .env   # optional overrides; no required variables
  

• 本番用バージョンをビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• チェックとテストを実行：

  bun run devcheck  # Lint, format, typecheck, security
  bun run test      # Vitest test suite
  bun run lint:mcp  # Validate MCP definitions against spec
  

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/openlibrary-mcp-server:latest

イメージは、HTTP トランスポート、ステートレスセッションモード、および /var/log/openlibrary-mcp-server へのログ出力をデフォルトで使用します。MCP クライアントから stdio 経由で実行するには、"command": "docker" と "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/openlibrary-mcp-server:latest"] を使用します。ローカルでビルドするには、docker build -t openlibrary-mcp-server . を実行します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドします。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() エントリーポイント。ツールとリソースを登録します。
src/config	Zod を使用した、サーバー固有の環境変数の解析と検証。
src/mcp-server/tools	ツール定義（*.tool.ts）。検索、書籍、著者、件名、表紙にわたる 10 個のツール。
src/mcp-server/resources	リソース定義（*.resource.ts）。作品と著者。
src/services/open-library	Open Library のサービスレイヤー。API クライアントとドメイン型。
skills/	公開されたエージェント向けガイダンス。MCP のスキル検出を通じても提供されます。
tests/	src/ の構成に対応するユニットテストと統合テスト。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch は使用しないでください。
• ログには ctx.log、ストレージには ctx.state を使用します。
• 新しいツールとリソースは、createApp() の配列に登録します。
• 外部 API 呼び出しは、入力値を検証し、ドメイン型に正規化してから、出力スキーマに従って返します。不足しているフィールドを捏造しないでください。

貢献

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 ライセンスの下でライセンスされています。詳細については、LICENSE ファイルを参照してください。