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

---

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

Tool	Description
get_me	Authenticated user's profile: id, username, name, bio, location, books count, followers, flair, pro status

Search

Tool	Arguments	Description
search	query, query_type?, per_page?, page?	Search books, authors, series, users, lists, characters, publishers, or prompts

Books

Tool	Arguments	Description
get_book_by_id	id	Full book details by Hardcover ID
get_book_by_slug	slug	Full book details by URL slug (e.g. the-name-of-the-wind)
get_editions_by_title	title	All editions matching an exact title
get_edition_by_id	id	Single edition details
get_editions_by_isbn	isbn	Look up edition by ISBN-10 or ISBN-13 (digits only)

Authors

Tool	Arguments	Description
get_author_by_id	id	Author profile by ID
get_author_by_slug	slug	Author profile by slug (e.g. brandon-sanderson)
get_author_books	author_id, limit?, offset?	Books by an author, ordered by popularity

Series

Tool	Arguments	Description
get_series_by_id	id	Series metadata: name, description, book count
get_books_in_series	series_id	Ordered, deduplicated book list — excludes partial books and compilations

My Library

Tool	Arguments	Description
get_my_library	limit?, offset?	Full library, all statuses, paginated
get_library_by_status	status_id, limit?, offset?	Library filtered by reading status
get_reading_progress	—	Currently-reading books with page progress
get_user_book	book_id	Your relationship with a book: status, rating, review, read sessions
get_my_reading_journal	book_id	Reading journal and session history for a book

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

Reading Statistics

Tool	Arguments	Description
get_reading_stats	user_id, since?	All-time count + avg rating, and filtered count since a date (YYYY-MM-DD). Use since=2026-01-01 for this year, since=2026-08-01 for this month
get_books_read_between	user_id, since, until, limit?, offset?	Books finished between two dates, ordered newest first

Goals

Tool	Arguments	Description
get_my_goals	—	All reading goals with progress, target, state, and dates

Activities

Tool	Arguments	Description
get_my_activities	user_id, limit?, offset?	Your activity feed (books added, rated, reviewed, goals, lists)
get_book_activities	book_id, limit?, offset?	Community activity for a specific book

Other Users

Tool	Arguments	Description
get_user_by_username	username	Look up a public user profile
get_user_library	user_id, status_id, limit?, offset?	Another user's library filtered by reading status

Lists

Tool	Arguments	Description
get_list_by_id	id	List details and its books (up to 50)

---

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

Plan	Daily	Burst	Per Minute
Free	5,000 req/day	10 req	60 req/min
Supporter	50,000 req/day	15 req	60 req/min

• 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.