Hardcover Mcp

hardcover-mcp

あらゆる AI アシスタントから Hardcover のライブラリを操作できます。

hardcover-mcp は、Hardcover のライブラリを Claude や Copilot などの AI アシスタントに接続します。本を検索したり、読書状況を更新したり、リストを管理したり、シリーズを調べたりできます。メニューをクリックして操作する代わりに、自然な会話で利用できます。

こんなことを頼めます

「現在読んでいる本のリストには何がありますか？」

「Project Hail Mary を現在読んでいる本としてライブラリに追加して」

「Brandon Sanderson の本を検索して」

「ISBN 9780547928227 を調べて」

「『夏の読書』というリストを作成して、The Hobbit を追加して」

「Stormlight Archive シリーズを読む順番で見せて」

「Project Hail Mary と The Martian を現在読んでいる本に移動して」

「Andy Weir が書いた本は何ですか？ まだ読んでいない本があれば、読みたい本のリストに追加して」

「Dune の評価を Hardcover の平均評価と比較して」

対応機能

• ライブラリの管理 — 状況、評価、読書日
• リストの管理 — 作成、編集、本の追加・削除
• 本の検索 — 本、著者、シリーズ、版などを検索
• アカウント情報 — プロフィールと読書統計

安全性と制御

• API キーは自分で管理 — お使いのマシンに保存され、第三者と共有されることはありません
• MCP クライアントを通じてローカルで実行 — 外部サーバーは使用しません
• 明示的に依頼した場合にのみ操作を実行 — バックグラウンドでは何も実行されません
• 送信前にクライアントでプロンプトと出力を確認できます
• 読み取り専用モード — HARDCOVER_READ_ONLY=true を設定すると、アカウントを変更できるツールをすべて非表示にします（設定を参照）
• 最小権限のキー — 必要なスコープのみをキーに付与できます。読み取り専用キーを使うと、Hardcover 自体が書き込みを拒否します（API キーとスコープを参照）

クイックスタート

1. uv をインストールします（高速な Python パッケージランナーです。セットアップは数秒で完了します）。
2. hardcover.app/account/api で API キーを作成します。適切なスコープがあらかじめ選択されたリンクについては、API キーとスコープを参照してください。
3. 以下の設定を MCP クライアントに追加します。手動でのインストールは不要で、uvx が処理します。

VS Code

.vscode/mcp.json に追加します。

{
  "servers": {
    "hardcover": {
      "command": "uvx",
      "args": ["hardcover-mcp"],
      "env": {
        "HARDCOVER_API_TOKEN": "<your token>",
        "HARDCOVER_TOOLSETS": "all",
        "HARDCOVER_READ_ONLY": "false"
      }
    }
  }
}

Claude Code

claude mcp add --scope user hardcover --env HARDCOVER_API_TOKEN=<your token> -- uvx hardcover-mcp

<your token> を Hardcover API キーに置き換えます。--scope user を指定すると、サーバーをすべてのプロジェクトで利用できます。省略すると、現在のプロジェクトのみに追加されます（スコープについてはClaude Code MCP ドキュメントを参照してください）。設定にあるその他の設定は、サーバー名の後ろに --env KEY=value フラグを追加します。たとえば、--env HARDCOVER_READ_ONLY=true のように指定します。

コマンドラインにトークンを表示させないようにするには、変数をファイルに記述し、uvx に読み込ませます。

claude mcp add --scope user hardcover -- uvx --env-file /path/to/hardcover.env hardcover-mcp

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "hardcover": {
      "command": "uvx",
      "args": ["hardcover-mcp"],
      "env": {
        "HARDCOVER_API_TOKEN": "<your token>",
        "HARDCOVER_TOOLSETS": "all",
        "HARDCOVER_READ_ONLY": "false"
      }
    }
  }
}

HARDCOVER_TOOLSETS と HARDCOVER_READ_ONLY は任意の設定で、既定値とともに表示されています。設定では、HARDCOVER_API_URL を含むすべての設定を一覧しています。

クライアント設定にトークンを記載しないようにするには、変数を .env ファイルに記述し、uvx にそのファイルを指定します。サーバーが読み込むのは、指定したファイルのみです。

"command": "uvx",
"args": ["--env-file", "/path/to/hardcover.env", "hardcover-mcp"]

API キーとスコープ

Hardcover API キーには、キーで実行できる操作を制限するスコープがあります。このサーバーに必要なスコープだけを指定してキーを作成してください（リンクを開くと、該当するスコープがあらかじめ選択された Hardcover のキー作成フォームが表示されます）。

• すべて: すべてのスコープを指定してキーを作成
• 読み取り専用: 読み取り専用キーを作成。これを HARDCOVER_READ_ONLY=true と組み合わせると、ツールが書き込みを試みても Hardcover が拒否します。

ツールセット	必要なスコープ
core	read:catalog、read:library、read:me、read:social、read:users
catalog	read:catalog、read:vibes
library	read:catalog、read:goals、read:library、read:lists、read:me、write:goals、write:library、write:reviews
lists	read:lists、read:me、write:lists
journal	read:journal、read:me、write:library
social	read:me、read:prompts、read:social、read:users、write:prompts、write:social

ほぼすべてのツールで read:me が必要です。これは、最初にユーザー情報を確認するためです。write:reviews は、set_user_book でレビューを作成または編集する場合にのみ必要です。このスコープがなくても、ステータス、評価、メモの変更は引き続き可能です。一部のツールセットだけを読み込む場合（設定を参照）、キーに必要なのは該当する行と core のスコープだけです。

• 2026年8月より前に作成されたキーはすべてのアクセス権を持ち、引き続き使用できます。
• キーを作成すると、Hardcover から有効期限を指定するよう求められます。有効期限を過ぎると、すべてのツールが「Hardcover rejected the API token … expired」というエラーと、新しいキーを作成するためのリンクを返します。
• ツールがキーにないスコープを必要とする場合、エラーには不足しているスコープが示され、それらがあらかじめ選択されたキー作成フォームへのリンクが表示されます。

設定

トークンと同じ env ブロックに設定する、任意の環境変数です。

変数	デフォルト	説明
HARDCOVER_TOOLSETS	all	読み込むツールセットをカンマ区切りで指定します。ツールを減らすと、使用するコンテキストが少なくなり、誤ったツールの選択も減ります。
HARDCOVER_READ_ONLY	false	true にすると、何かを作成、変更、削除するすべてのツールが非表示になります。
HARDCOVER_API_URL	Hardcover の API	代わりに呼び出す GraphQL エンドポイント（プロキシなど）を指定します。すべてのリクエストにトークンが含まれるため、https:// である必要があります。

ツールセット	対象範囲
core	常に読み込み：search_books、get_user
catalog	書籍（登場人物と版を含む）、版、著者、シリーズ、出版社、トレンド、雰囲気
library	自分のライブラリ、読書日と進捗、所有状況、レビュー、統計、目標
lists	リストの表示と管理
journal	読書ジャーナルのメモと引用
social	アクティビティフィード、ユーザーのフォロー、コミュニティのプロンプト

たとえば、書籍と自分のライブラリを閲覧するための読み取り専用アシスタントは次のとおりです。

"env": {
  "HARDCOVER_API_TOKEN": "<your token>",
  "HARDCOVER_TOOLSETS": "catalog,library",
  "HARDCOVER_READ_ONLY": "true"
}

不明なツールセット名を指定すると、サーバーは有効な名前の一覧を含むメッセージを表示して、起動時に停止します。

ツール

ツールセットごとに分類されています（設定を参照）。✏️ が付いたツールはアカウントを変更でき、読み取り専用モードでは非表示になります。

core（常に読み込み）

できること	ツール
書籍、著者、シリーズ、リスト、ユーザーなどを検索します（並べ替え／フィルター付き）	search_books
自分のプロフィールや読書統計を確認するか、別のユーザーを検索します。ライブラリ、フォロワー、フォロー中のユーザーも指定できます	get_user

カタログ

できること	ツール
ID またはスラッグで書籍を検索し、寄稿者とその役割（必要に応じて登場人物や版も含む）を確認するか、ISBN、ASIN、または版 ID で特定の版を検索します	get_book
著者の作品一覧を閲覧します	get_author
シリーズを読書順に確認します	get_series
出版社とその版を検索します	get_publisher
現在の人気作品を確認します	get_trending_books
厳選されたおすすめコレクション（雰囲気）を閲覧します	get_vibes

ライブラリ

できること	ツール
ライブラリを閲覧します。ステータス、期間、レビュー済みかどうか、所有状況で絞り込み、評価や日付で並べ替えられます	get_user_library
1 冊の書籍について、ステータス、評価、レビュー、読書記録、リストへの登録状況を確認します（内部の「所有」リストを除く）	get_user_book
現在の読書目標と進捗を確認します	get_reading_goal
✏️ 書籍を追加するか、ステータス、評価、レビュー、メモ、公開設定、版、所有状況を更新します	set_user_book
✏️ 読書日や進捗（ページ数、オーディオブックの再生時間）を記録または編集します	set_user_book_read
✏️ 読書目標（冊数／ページ数、期間）を作成、更新、またはアーカイブします	set_reading_goal
✏️ 読書目標を削除します	delete_reading_goal
✏️ 読書記録または書籍全体を削除します	delete_user_book_read / delete_user_book

リスト

できること	ツール
リスト、または書籍を含む特定のリストを表示します	get_list
✏️ リストを作成または名前変更するか、公開設定を変更します	set_list
✏️ 1 つのリスト（list_id）または最大 20 個のリスト（list_ids）に書籍を追加または削除します	set_list_book
✏️ リストを削除します	delete_list

日記

できること	ツール
日記の記録（メモ、引用、ステータスの変更履歴）を読みます	get_reading_journal
✏️ 日記のメモ／引用を追加または編集します	set_journal_entry
✏️ 日記の記録を削除します	delete_journal_entry

ソーシャル

できること	ツール
フォローしている人（または特定のユーザー）の最近のアクティビティを確認します	get_activity_feed
✏️ ユーザーをフォローまたはフォロー解除します	set_following
コミュニティの書籍プロンプトを閲覧します	get_prompts
✏️ 書籍でプロンプトに回答するか、回答を取り消します	set_prompt_answer

開発

git clone https://github.com/kristianedlund/hardcover-mcp.git
cd hardcover-mcp
uv sync

Lint とフォーマットのチェック（Ruff を使用）：

uv run ruff check .
uv run ruff format --check .

テストを実行します：

uv run pytest tests/ -v

統合テスト

統合テストは稼働中の Hardcover API にアクセスするため、有効なトークンが必要です。CI 環境では、またトークンがない場合は、自動的にスキップされます。

ローカルで実行するには、リポジトリ内にトークンを記述した .env ファイルを作成してください（テストはこのファイルを読み込みますが、サーバー自体は実際の環境変数のみを読み取ります）：

HARDCOVER_API_TOKEN=your_token_here

次に、以下を実行します：

uv run pytest tests/integration/ -v

書き込みテストは、作成 → 検証 → 削除のライフサイクルに従うため、アカウントの状態は変更されません。

貢献

貢献を歓迎します。以下の手順に従ってください。

1. まず issue を作成し、変更について話し合います。
2. リポジトリをフォークして、ブランチ（feature/short-description または fix/short-description）を作成します。
3. 提出前に lint とテストを実行します：

   uv run ruff check .
   uv run ruff format --check .
   uv run pytest tests/ -v
   

4. PR の範囲を絞り、1 つの PR につき変更を 1 つにします。
5. Conventional Commits のプレフィックスを使用します：feat:、fix:、chore:、docs:。

レート制限

Hardcover API では、短時間のバースト許容量付きで毎分 60 件のリクエストが許可され、さらに 1 日あたりの上限があります（無料プランでは 5,000 件）。サーバーはリクエストをキューに入れ、API のレート制限ヘッダーに従い、待機を求められた場合は再試行します。一度に待機する時間は最大 1 分です。Hardcover がそれより長い待機時間を求めた場合、呼び出しを停止し、待機時間を通知します。1 日あたりの上限に達すると、すぐに停止してその旨を通知します（上限は UTC の午前 0 時にリセットされます）。利用状況は hardcover.app/account/api で確認できます。2026 年 8 月以降に作成されたキーは、それ以前のキーの 2 倍のバースト許容量があります。

トラブルシューティング

問題	対処方法
「API token is not set」	設定にトークンを追加してください（上記のクイックスタートを参照）
「Hardcover rejected the API token」	キーが無効か期限切れです。エラー内のリンクから新しいキーを作成してください
「missing the scope(s) this tool needs」	必要なスコープを含むキーを作成してください。エラー内のリンクから、入力済みのフォームにアクセスできます
「daily API limit … is used up」	UTC の午前0時まで待つか、読み込むツールを減らして API 呼び出しを減らしてください
「rate limit asks to wait N seconds」	Hardcover がこのキーのリクエストを制限しています。その時間が経過してから再試行してください
「Hardcover didn't answer within 30 seconds」	再試行してください。変更を依頼した場合は、まず保存されたかどうかを確認してください
Windows で「Access is denied」	設定の env ブロックに "UV_LINK_MODE": "copy" を追加してください
動作が遅い、またはエラーが繰り返し発生する	サーバーは自動的に再試行します。少し待ってから再試行してください
予期しない結果	新しいバージョンがないか確認してください。Hardcover API が変更されている可能性があります

免責事項

非公式プロジェクトです。Hardcover とは提携していません。