hardcover-mcp

⚠️ Beta v0.1.0 — Dies ist eine frühe Version. Die API-Oberfläche, die Tool-Namen und die Abfragestruktur können sich ändern. Bitte melden Sie Probleme und Feedback über GitHub Issues.

Ein Model Context Protocol (MCP)-Server für die Hardcover-API – die Buch-Tracking-Plattform, die für ihre Website sowie für iOS- und Android-Apps dieselbe GraphQL-API verwendet.

Verbinden Sie jeden MCP-kompatiblen KI-Assistenten (Claude Desktop, Cursor, Kiro oder jeden anderen MCP-Client) direkt mit Ihrer Hardcover-Bibliothek, Ihrem Leseverlauf, Ihren Zielen und dem vollständigen Hardcover-Buchkatalog.

Inhaltsverzeichnis

• Funktionen

• Tool-Referenz

• Voraussetzungen

• Installation

• Konfiguration

• Verwendung

  • Claude Desktop

  • Kiro CLI

  • Andere MCP-Clients

• Ratenlimits & API-Richtlinie

• Haftungsausschluss

• Entwicklung

• Mitwirken

• Lizenz

Related MCP server: hardcover-mcp

Funktionen

• 🔍 Suche nach Büchern, Autoren, Serien, Benutzern, Listen, Figuren, Verlagen und Prompts

• 📚 Bibliothek durchsuchen – alle Status, gefilterte Ansichten und paginierte Ergebnisse

• 📖 Lesefortschritt – aktuell gelesene Bücher mit Fortschritt auf Seitenebene

• 📊 Lesestatistiken – diesen Monat, dieses Jahr und insgesamt gelesene Bücher mit Durchschnittsbewertungen

• 🎯 Leseziele – Fortschritt, Status und Zielwert für all Ihre Ziele

• 🗓️ Bücher nach Zeitraum – listet jedes Buch auf, das Sie zwischen zwei Daten beendet haben

• 📓 Lesetagebuch – Sitzungsverlauf pro Buch

• 👤 Benutzerprofile – Ihr Profil und öffentliche Profile per Benutzername

• 📋 Listen – jede Hardcover-Liste mit ihren Büchern abrufen

• 🏃 Aktivitätsfeed – Ihre letzten Aktivitäten und Aktivitäten zu bestimmten Büchern

• 🔖 Ausgaben – per Titel, ID oder ISBN-10/13 nachschlagen

• ✍️ Autoren – Profile und Bibliografien

• 📚 Serien – geordnete, duplikatfreie Buchlisten

Tools-Referenz

Identität

Suche

Bücher

Autoren

Serien

Meine Bibliothek

Status-IDs: 1 Möchte ich lesen · 2 Lese gerade · 3 Gelesen · 4 Pausiert · 5 Nicht beendet · 6 Ignoriert

Lesestatistiken

Ziele

Aktivitäten

Andere Benutzer

Listen

Voraussetzungen

• Python 3.10 oder neuer

• uv (empfohlen) oder pip

• Ein Hardcover-API-Schlüssel – erhalten Sie Ihren unter hardcover.app/account/api

Installation

Mit uv (empfohlen)

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

Mit pip

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

Über PyPI (sobald veröffentlicht)

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

Konfiguration

Kopieren Sie .env.example in .env und fügen Sie Ihren API-Schlüssel ein:

cp .env.example .env

HARDCOVER_API_KEY=your_api_key_here

Bewahren Sie Ihre Daten sicher auf. Ihr Personal Access Token hat Zugriff auf Ihr Hardcover-Konto. Committen Sie es niemals in die Versionskontrolle, teilen Sie es nicht öffentlich und betten Sie es nicht in clientseitigen Code ein.

Verwendung

Claude Desktop

Fügen Sie in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %APPDATA%\Claude\claude_desktop_config.json (Windows) hinzu:

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

Oder falls Sie es per pip/uv in einer virtuellen Umgebung installiert haben:

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

Kiro CLI

Fügen Sie zu ~/.kiro/settings/mcp.json hinzu:

{
  "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": []
    }
  }
}

Andere MCP-Clients

Richten Sie Ihren Client auf den Eintrittspunkt hardcover-mcp (oder python -m hardcover.server) aus und setzen Sie HARDCOVER_API_KEY in der Umgebung. Der Server kommuniziert über stdio und ist mit jedem MCP-1.0+-Client kompatibel.

Ratengrenzen & API-Richtlinie

Bitte lesen Sie dies, bevor Sie mit diesem Server bauen. Die Hardcover-API ist kostenlos nutzbar, hat aber feste Grenzen. Ein unerwartetes Erreichen dieser Grenzen kann Ihren Workflow unterbrechen.

Ratenlimits

• Tageslimit: harte Obergrenze. Sobald es erreicht ist, liefern alle Anfragen 429 zurück, bis Mitternacht UTC.

• Burst-Limit: wie viele Anfragen Sie direkt hintereinander senden können, bevor gedrosselt wird. Es füllt sich kontinuierlich mit der Rate pro Minute wieder auf.

• Pro-Minute-Limit: 60 Anfragen/Min für alle Tarife (token bucket).

• Limit pro Anfrage: Eine einzelne GraphQL-Anfrage darf höchstens 5 Top-Level-Abfragen enthalten. Wird dies überschritten, gibt es 403 statt 429.

• Personal Access Tokens erhalten die doppelte Burst-Kapazität als die ältere JWT-Authentifizierung im selben Tarif.

Dieser MCP-Server liefert retry_after-Hinweise, wenn eine 429 zurückgegeben wird, damit Ihr KI-Assistent elegant zurücktreten kann.

Gewerbliche Nutzung

Gemäß Hardcovers API-Richtlinie:

• Vom Benutzer erstellte Daten (Bibliotheken, Bewertungen, Rezensionen, Journaleinträge, Listen, Ziele) dürfen nicht in kommerziellen Produkten verwendet werden, außer Sie handeln im Auftrag eines Benutzers, der den Zugriff ausdrücklich gewährt hat.

• Aggregierte, anonymisierte Daten (z. B. Anzahl der Hardcover-Leser, Durchschnittsheimswert) dürfen kommerziell verwendet werden, wenn Hardcover als Quelle angegeben wird.

• Bilder, die von Hardcover ausgeliefert werden, sind von Benutzern hochgeladen. Wenn Sie sie öffentlich anzeigen, müssen Sie eine [DMCA-Entrichtungsrichtlinie] (https://hardcover-Entferung) (https://hardcover.app/pages/dmca) bereitstellen.

Verbotene Abfragemuster

Die folgenden GraphQL-Operatoren sind über die API deaktiviert:

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

Abfragen müssen serverseitig ausgeführt werden

Die Hardcover-API darf nicht aus einem Browser aufgerufen werden. Ihr API-Schlüssel muss in einer sicheren Serverumgebung aufbewahrt werden.

Weitere Details erhalten Sie im offiziellen Leitfaden „Erste Schritte“.

Haftungsausschluss

Dies ist eine Beta-Version (v0.1.0). Es handelt sich um unabhängige, von der Community entwickelte Software, die nicht mit Hardcover verbunden ist und von Hardcover weder befürwortet noch unterstützt wird.

• Die Hardcover-API befindet sich selbst in der Beta und unterliegt Breaking Changes.

• Toolnamen, Abfragestruktur und Antwortformate in diesem MCP-Server können sich zwischen den Versionen ändern.

• Die Verwendung in Produktions- oder kommerziellen Kontexten erfolgt vollständig auf eigenes Risiko.

• Durch die Verwendung der Hardcover-API über diesen Server stimmen Sie den Richtlinien von Hardcover zu.

Entwicklung

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

Projektstruktur

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

Tests ausführen

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

Mitwirken

Beiträge sind willkommen. Bitte:

1. Eröffnen Sie zuerst ein Issue, um bedeutende Änderungen zu besprechen

2. Folgen Sie dem bestehenden Code-Stil

3. Ergänzen oder aktualisieren Sie Tests für jedes geänderte Verhalten

4. Halten Sie PRs fokussiert – eine Funktion oder ein Fix pro PR

Lizenz

MIT – siehe LICENSE für Details.