Skip to main content
Glama
hardcover-mcp

hardcover-mcp

by muhyousri

hardcover-mcp

⚠️ Beta v0.1.1 — 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


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 other users' libraries

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

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_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


Installation

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

With pip

git clone https://github.com/muhyousri/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/muhyousri/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.

Available Tools

25 tools
get_author_booksA

Get books written by a specific author, ordered by popularity.

Inputs: author_id (required), limit, offset.

get_author_by_idA

Get an author's profile by Hardcover author ID.

Inputs: id (required).

get_author_by_slugA

Get an author's profile by URL slug (e.g. 'brandon-sanderson').

Inputs: slug (required).

get_book_activitiesA

Get recent user activity for a specific book (ratings, reviews, status changes).

Inputs: book_id (required), limit, offset.

get_book_by_idB

Get full book details by Hardcover book ID.

Inputs: id (required).

get_book_by_slugA

Get full book details by Hardcover URL slug (e.g. 'the-name-of-the-wind').

Inputs: slug (required).

get_books_in_seriesA

Get the ordered, deduplicated list of books in a series. Merges duplicates, excludes partial books and compilations.

Inputs: series_id (required).

get_books_read_betweenA

List books marked as Read with a finish date between two dates, ordered most-recent first.

Inputs: since (required), until (required), user_id (required), limit, +1 more.

get_edition_by_idA

Get detailed information about a specific edition by its ID.

Inputs: id (required).

get_editions_by_isbnB

Look up an edition by ISBN-10 or ISBN-13.

Inputs: isbn (required).

get_editions_by_titleA

Get all known editions of a book by exact title match.

Inputs: title (required).

get_library_by_statusA

Get the authenticated user's books filtered by reading status. Status IDs: 1=Want to Read, 2=Currently Reading, 3=Read, 4=Did Not Finish, 5=Owned.

Inputs: status_id (required), limit, offset.

get_list_by_idA

Get a Hardcover list's details and its books (up to 50 books).

Inputs: id (required).

get_meA

Get the currently authenticated Hardcover user's profile (id, username, name, book counts).

Inputs: no named parameters.

get_my_activitiesA

Get a user's recent activity feed (books added, rated, reviewed, goals, lists). Requires the user's numeric ID.

Inputs: user_id (required), limit, offset.

get_my_goalsA

Get the authenticated user's reading goals (progress, target, state, dates).

Inputs: no named parameters.

get_my_libraryA

Get the authenticated user's full library (all statuses), paginated.

Inputs: limit, offset.

get_my_reading_journalB

Get reading journal entries and session history for a specific book.

Inputs: book_id (required).

get_reading_progressB

Get all books currently being read with their page-level progress.

Inputs: no named parameters.

get_reading_statsA

Get reading statistics: total books read all-time AND since an optional date (e.g. '2026-01-01' for this year, '2026-08-01' for this month), plus average rating for each window. Requires the user's numeric ID (use get_me to find it).

Inputs: user_id (required), since.

get_series_by_idA

Get series metadata (name, description, book count) by series ID.

Inputs: id (required).

get_user_bookA

Get the authenticated user's relationship with a specific book (status, rating, review, read sessions).

Inputs: book_id (required).

get_user_by_usernameB

Look up a public Hardcover user profile by username.

Inputs: username (required).

get_user_libraryA

Get another user's library filtered by reading status. Status IDs: 1=Want to Read, 2=Currently Reading, 3=Read, 4=Did Not Finish, 5=Owned.

Inputs: user_id (required), status_id (required), limit, offset.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools map cleanly to distinct resources: books, editions, authors, series, users, libraries, progress, stats, and activities. The main minor ambiguities are the parallel id/slug lookups for books/authors and the broad `search` tool, but these are clearly separated by input type.

    Naming Consistency5/5

    The overwhelming majority of tools follow a predictable `get_<resource>` or `get_<resource>_by_<key>` snake_case pattern. The single standalone `search` tool is a minor but logical exception, and it does not disrupt the overall consistency.

    Tool Count3/5

    25 tools is at the boundary where a server starts to feel heavy, though each tool is a distinct read-only lookup in a rich book/reading domain. Some consolidation, especially around edition lookups and library/status variants, could reduce redundancy without losing functionality.

    Completeness4/5

    The read-only surface is strong: it covers books, editions, authors, series, users, libraries, reading progress, stats, lists, and activities. However, it offers no create/update/delete capabilities for library status, ratings, reviews, or lists, so users expecting a full reading-app workflow will hit dead ends.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to help users manage their reading experience by searching books, tracking reading progress, managing bookmarks, and generating personalized recommendations and summaries.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Connects AI assistants to the Hardcover book library, enabling natural language book searches, reading status updates, list management, and library exploration.
      28
      143 PyPI
      10
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Connects MCP clients to a Calibre ebook library for semantic search, metadata curation, and library management via natural language.
      19
      590 npm
      31
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude, ChatGPT, and other MCP clients to read and manage a Hardcover account's library, reading progress, reviews, journal, lists, goals, follows, and notifications through 53 read/write tools. It is a hosted remote server that connects each user to their own account via Hardcover's OAuth sign-in, with six raw GraphQL tools reaching anything else in the API.
      3
      MIT