hardcover-mcp

⚠️ Beta v0.1.0 — これは早期リリースです。API サーフェス、ツール名、クエリ構造は変更される可能性があります。問題やフィードバックは GitHub Issues でご報告ください。

Hardcover API 用の Model Context Protocol (MCP) サーバーです。Hardcover は、ウェブサイト、iOS、Android アプリで同じ GraphQL API を使用する書籍トラッキングプラットフォームです。

MCP 互換の AI アシスタント（Claude Desktop、Cursor、Kiro、またはその他の MCP クライアント）を、Hardcover のライブラリ、読書履歴、目標、そして Hardcover の全書籍カタログに直接接続できます。

目次

• 機能

• ツールリファレンス

• 要件

• インストール

• 設定

• 使い方

  • Claude Desktop

  • Kiro CLI

  • その他の MCP クライアント

• レート制限と API ポリシー

• 免責事項

• 開発

• コントリビュート

• ライセンス

Related MCP server: hardcover-mcp

機能

• 検索 書籍、著者、シリーズ、ユーザー、リスト、登場人物、出版社、プロンプト

• ライブラリの閲覧 すべてのステータス、フィルタリングされた表示、ページネーション対応

• 読書進捗 ページ単位の進捗を含む現在読書中の書籍

• 読書統計 今月、今年、全期間で読んだ書籍と平均評価

• 読書目標 すべての目標の進捗、状態、目標値

• 日付範囲で書籍を検索 2つの日付の間に読了したすべての書籍をリスト表示

• 読書ジャーナル 書籍ごとのセッション履歴

• ユーザープロフィール 自分のプロフィールと、ユーザー名による公開プロフィール

• リスト 任意の Hardcover リストとその書籍を取得

• アクティビティフィード 自分の最近のアクティビティと、特定の書籍に関するアクティビティ

• エディション タイトル、ID、ISBN-10 / ISBN-13 で検索

• 著者 プロフィールと書誌

• シリーズ 順序付けられ、重複が除去されたランキング

ツールリファレンス

アイデンティティ

検索

書籍

著者

シリーズ

マイライブラリ

ステータス ID: 1 読みたい · 2 読書中 · 3 読了 · 4 一時停止 · 5 読了しない · 6 無視

読書統計

目標

アクティビティ

他のユーザー

リスト

要件

• Python 3.10 以上

• uv（推奨）または pip

• Hardcover API キー — hardcover.app/account/api から入手できます

インストール

uv を使う場合（推奨）

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

pip を使う場合

git clone https://github.com/YOUR_USERNAME/hardcover-mcp
cd hardcover-mcp
pip install -e .

PyPI から（公開後）

uv pip install hardcover-mcp
# or
pip install hardcover-mcp

設定

.env.example を .env にコピーし、API キーを追加します:

cp .env.example .env

HARDCOVER_API_KEY=your_api_key_here

トークンをシークレットにしてください。 自分の Personal Access Token は自分の Hardcover アカウントにアクセスできます。 バージョン管理にコミットしたり、公開したり、クライアントサイドのコードに埋め込んだりすることは絶対にしないでください。

使い方

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加:

{
  "mcpServers": {
    "hardcover": {
      "command": "uv",
      "args": [
        "run",
        "--with-editable",
        "/path/to/hardcover-mcp",
        "hardcover-mcp"
      ],
      "env": {
        "HARDCOVER_API_KEY": "your_api_key_here"
      }
    }
  }
}

または、pip / uv で venv にインストールした場合:

{
  "mcpServers": {
    "hardcover": {
      "command": "/path/to/venv/bin/hardcover-mcp",
      "env": {
        "HARDCOVER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Kiro CLI

~/.kiro/settings/mcp.json に追加:

{
  "mcpServers": {
    "hardcover": {
      "command": "/path/to/uv",
      "args": [
        "run",
        "--with-editable",
        "/path/to/hardcover-mcp",
        "hardcover-mcp"
      ],
      "env": {
        "HARDCOVER_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

その他の MCP クライアント

HARDCOVER_API_KEY を環境変数に設定し、クライアントを hardcover-mcp エントリポイント（または python -m hardcover.server）に指定してください。サーバーは stdio で通信し、MCP 1.0+ 互換のクライアントすべてに対応しています。

レート制限と API ポリシー

このサーバーをビルドする前に必ずお読みください。 Hardcover の API は無料で使用できますが、厳格な制限があります。予想外に制限を超えると、ワークフローを中断する可能性があります。

レート制限

• 1日のリクエスト制限: 完全な上限。一度到達すると、UTC の翌日になるまで全てのリクエストが 429 を返します。

• バースト制限: スロットラーがかかるまでに連続して送信できるリクエスト数。毎分のレートで補充されます。

• 1分あたりの制限: 全プランで 60 req / min (token bucket)。

• リクエストあたりの制限: 1 つの GraphQL リクエストには最大 5 つのトップレベルクエリを含めることができます。超過すると 429 ではなく 403 が返ります。

• Personal Access Token は、同じプランの旧式 JWT 認証と比べてバースト容量が 2 倍になります。

この MCP サーバーは、429 が返されたときに retry_after ヒントを表示するため、AI アシスタントは上手にバックオフできます。

商用利用について

Hardcover の API ポリシー により:

• ユーザー所有のデータ（ライブラリ、評価、レビュー、ジャーナル、リスト、目標）は、明らかな許可を得たユーザーに代わって使用する場合を除き、商用プロダクトに使用することはできません。

• 集計・匿名化されたデータ（例: Hardcover の読者数、Hardcover の平均評価）は、クリエジットを記載することで商用利用できます。

• Hardcover で配信される画像はユーザーがアップロードしたものです。公開表示する場合は、DMCA 削除ポリシーが必要です。

禁止されているクエリパターン

以下の GraphQL オペレータは API では無効です:

_like, _nlike, _ilike, _niregex, _nregex, _iregex, _regex, _nsimilar, _similar

クエリはサーバーサイドで実行する必要があります

Hardcover API をブラウザで呼び出してはいけません。API キーは安全なサーバー環境に保持してください。

詳しくは、公式の Getting Started Guide を参照してください。

免責事項

このドキュメントは情報提供を目的としており、特定の結果を保証するものではありません。各ユーザーは自己責任のもとで使用してください。

これはベータリリース（v0.1.0）です。 これは独立したコミュニティ製ソフトウェアであり、Hardcoverとの提携、承認、サポートは一切ありません。

• Hardcover APIはそれ自体がベータ版であり、破壊的な変更が行われる可能性があります。

• このMCPサーバーのツール名、クエリ構造、レスポンス形式は、バージョン間で変更される場合があります。

• 本番環境や商用での利用は、すべて自己責任となります。

• このサーバーを介してHardcover APIを利用することで、Hardcoverのポリシーに同意したものとみなされます。

開発

git clone https://github.com/YOUR_USERNAME/hardcover-mcp
cd hardcover-mcp

# Create virtualenv and install with dev deps
uv sync --extra dev
# or: pip install -e ".[dev]"

# Run tests
uv run pytest
# or: python -m pytest

# Run the server locally (needs HARDCOVER_API_KEY in environment)
HARDCOVER_API_KEY=your_key hardcover-mcp

プロジェクト構成

hardcover-mcp/
├── hardcover/
│   ├── __init__.py
│   ├── client.py      # GraphQL HTTP client, rate-limit handling, error mapping
│   ├── queries.py     # All GraphQL query strings
│   └── server.py      # MCP server, tool definitions, dispatch
├── tests/
│   ├── conftest.py    # Shared fixtures
│   ├── test_client.py # 30 client tests (HTTP errors, rate limits, response parsing)
│   └── test_server.py # 51 server tests (tool dispatch, error formatting)
├── .env.example
├── .gitignore
├── pyproject.toml
└── README.md

テストの実行

pytest                  # all tests
pytest tests/test_client.py   # client only
pytest tests/test_server.py   # server only
pytest -v               # verbose

コントリビューション

コントリビューションを歓迎します。以下のようにお願いいたします：

1. 重要な変更は、まずissueを開いて相談してください

2. 既存のコードスタイルに従ってください

3. 変更した動作に合わせてテストを追加または更新してください

4. PRは焦点を絞ってください — 1つのPRにつき、1つの機能または修正を入れてください

ライセンス

MIT — 詳細はLICENSEを参照してください。