hardcover-mcp
This server lets an MCP-compatible AI assistant interact with a user's Hardcover book-tracking account and the broader Hardcover catalogue via 23 tools.
Identity: view the authenticated user's profile (
get_me)Search: search books, authors, series, users, lists, characters, publishers, and prompts
Books & editions: look up books by ID/slug, editions by title/ID/ISBN
Authors & series: view author profiles/bibliographies and ordered series book lists
Personal library: browse all books or filter by reading status, see reading progress and per-book status/rating/review
Statistics & history: get reading stats and books finished between dates
Goals: view reading goals with progress and targets
Activities: view the user's activity feed and activity on specific books
Other users: look up user profiles and their libraries by status
Lists: retrieve list details and contained books
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hardcover-mcp Show me my reading progress and stats for this year."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Authenticated user's profile: id, username, name, bio, location, books count, followers, flair, pro status |
Search
Tool | Arguments | Description |
|
| Search books, authors, series, users, lists, characters, publishers, or prompts |
Books
Tool | Arguments | Description |
|
| Full book details by Hardcover ID |
|
| Full book details by URL slug (e.g. |
|
| All editions matching an exact title |
|
| Single edition details |
|
| Look up edition by ISBN-10 or ISBN-13 (digits only) |
Authors
Tool | Arguments | Description |
|
| Author profile by ID |
|
| Author profile by slug (e.g. |
|
| Books by an author, ordered by popularity |
Series
Tool | Arguments | Description |
|
| Series metadata: name, description, book count |
|
| Ordered, deduplicated book list — excludes partial books and compilations |
My Library
Tool | Arguments | Description |
|
| Full library, all statuses, paginated |
|
| Library filtered by reading status |
| — | Currently-reading books with page progress |
|
| Your relationship with a book: status, rating, review, read sessions |
|
| 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 |
|
| All-time count + avg rating, and filtered count since a date ( |
|
| Books finished between two dates, ordered newest first |
Goals
Tool | Arguments | Description |
| — | All reading goals with progress, target, state, and dates |
Activities
Tool | Arguments | Description |
|
| Your activity feed (books added, rated, reviewed, goals, lists) |
|
| Community activity for a specific book |
Other Users
Tool | Arguments | Description |
|
| Another user's library filtered by reading status |
Lists
Tool | Arguments | Description |
|
| 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/muhyousri/hardcover-mcp
cd hardcover-mcp
uv syncWith 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-mcpConfiguration
Copy .env.example to .env and add your API key:
cp .env.example .envHARDCOVER_API_KEY=your_api_key_hereKeep 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
429until 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, not429.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
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-mcpProject 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.mdRunning tests
pytest # all tests
pytest tests/test_client.py # client only
pytest tests/test_server.py # server only
pytest -v # verboseContributing
Contributions are welcome. Please:
Open an issue first to discuss significant changes
Follow the existing code style
Add or update tests for any changed behaviour
Keep PRs focused — one feature or fix per PR
License
MIT — see LICENSE for details.
Available Tools
25 toolsget_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.
searchA
Search Hardcover for books, authors, series, users, lists, characters, publishers, or prompts. Returns rich result objects from Typesense. query_type defaults to 'book'.
Inputs: query (required), page, per_page, query_type.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
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.
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.
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.
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
Related MCP Connectors
Read and update your Hardcover library, progress, lists, and goals. Sign in with Hardcover OAuth.
The media memory layer for AI agents and their humans. Your AI client can search your collection, add and log what you've finished, update ratings and lists, and find patterns across everything you've read, watched, played, and listened to.
AI assistant integration for Leaf — track books, log reading sessions, and manage your library.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to help users manage their reading experience by searching books, tracking reading progress, managing bookmarks, and generating personalized recommendations and summaries.-
- AlicenseAqualityBmaintenanceConnects AI assistants to the Hardcover book library, enabling natural language book searches, reading status updates, list management, and library exploration.28143 PyPI10MIT
- AlicenseAqualityBmaintenanceConnects MCP clients to a Calibre ebook library for semantic search, metadata curation, and library management via natural language.19590 npm31MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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.3MIT