hardcover-mcp

⚠️ Beta v0.1.0 — This is an early release. The API surface, tool names, and query structure may change. Please report issues and feedback via GitHub Issues.

A Model Context Protocol (MCP) server for the Hardcover API — the book-tracking platform that uses the same GraphQL API for its website, iOS, and Android apps.

Connect any MCP-compatible AI assistant (Claude Desktop, Cursor, Kiro, or any MCP client) directly to your Hardcover library, reading history, goals, and the full Hardcover book catalogue.

Contents

• Features

• Tools Reference

• Requirements

• Installation

• Configuration

• Usage

  • Claude Desktop

  • Kiro CLI

  • Other MCP Clients

• Rate Limits & API Policy

• Disclaimer

• Development

• Contributing

• License

Related MCP server: hardcover-mcp

Features

• 🔍 Search books, authors, series, users, lists, characters, publishers, and prompts

• 📚 Browse your library — all statuses, filtered views, and paginated results

• 📖 Reading progress — currently-reading books with page-level progress

• 📊 Reading statistics — books read this month, this year, all time, with average ratings

• 🎯 Reading goals — progress, state, and target for all your goals

• 🗓️ Books by date range — list every book you finished between two dates

• 📓 Reading journal — per-book session history

• 👤 User profiles — your profile and public profiles by username

• 📋 Lists — retrieve any Hardcover list with its books

• 🏃 Activity feed — your recent activity and activity on specific books

• 🔖 Editions — look up by title, ID, or ISBN-10/13

• ✍️ Authors — profiles and bibliography

• 📖 Series — ordered, deduplicated book lists

Tools Reference

Identity

Search

Books

Authors

Series

My Library

Status IDs: 1 Want to Read · 2 Currently Reading · 3 Read · 4 Paused · 5 Did Not Finish · 6 Ignored

Reading Statistics

Goals

Activities

Other Users

Lists

Requirements

• Python 3.10 or later

• uv (recommended) or pip

• A Hardcover API key — get yours at hardcover.app/account/api

Installation

With uv (recommended)

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

With pip

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

From PyPI (once published)

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

Configuration

Copy .env.example to .env and add your API key:

cp .env.example .env

HARDCOVER_API_KEY=your_api_key_here

Keep your token private. Your Personal Access Token has access to your Hardcover account. Never commit it to version control, share it publicly, or embed it in client-side code.

Usage

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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"
      }
    }
  }
}

Or if installed via pip/uv into a virtualenv:

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

Kiro CLI

Add to ~/.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": []
    }
  }
}

Other MCP Clients

Point your client at the hardcover-mcp entrypoint (or python -m hardcover.server) with HARDCOVER_API_KEY set in the environment. The server communicates over stdio and is compatible with any MCP 1.0+ client.

Rate Limits & API Policy

Please read before building with this server. Hardcover's API is free to use but has firm limits. Hitting them unexpectedly can disrupt your workflow.

Rate Limits

• Daily limit: hard cap. Once reached, all requests return 429 until midnight UTC.

• Burst limit: how many requests you can fire back-to-back before throttling. Refills continuously at the per-minute rate.

• Per-minute limit: 60 req/min for all plans (token bucket).

• Per-request limit: a single GraphQL request may contain at most 5 top-level queries. Exceeding this returns 403, not 429.

• Personal Access Tokens get double the burst capacity vs. legacy JWT auth on the same plan.

This MCP server surfaces retry_after hints when a 429 is returned, so your AI assistant can back off gracefully.

Commercial Use

Per Hardcover's API policy:

• User-owned data (libraries, ratings, reviews, journal entries, lists, goals) may not be used in commercial products unless you are acting on behalf of a user who has explicitly granted access.

• Aggregate, anonymised data (e.g. number of Hardcover readers, average Hardcover rating) may be used commercially if credited to Hardcover.

• Images served from Hardcover are user-uploaded. If you display them publicly, you must have a DMCA takedown policy.

Prohibited Query Patterns

The following GraphQL operators are disabled by the API:

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

Queries must run server-side

The Hardcover API may not be called from a browser. Your API key must be kept in a secure server environment.

For more details see the official Getting Started guide.

Disclaimer

This is a beta release (v0.1.0). It is independent, community-built software and is not affiliated with, endorsed by, or supported by Hardcover.

• The Hardcover API is itself in beta and subject to breaking changes.

• Tool names, query structure, and response shapes in this MCP server may change between versions.

• Use in production or commercial contexts is entirely at your own risk.

• By using the Hardcover API via this server, you agree to Hardcover's policies.

Development

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

Project structure

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

Running tests

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

Contributing

Contributions are welcome. Please:

1. Open an issue first to discuss significant changes

2. Follow the existing code style

3. Add or update tests for any changed behaviour

4. Keep PRs focused — one feature or fix per PR

License

MIT — see LICENSE for details.