Skip to main content

hardcover-mcp

PyPI License: MIT Python 3.14+

Talk to your Hardcover library from any AI assistant.

hardcover-mcp connects your Hardcover library to AI assistants like Claude and Copilot. Search for books, update your reading status, manage lists, explore series — all through natural conversation instead of clicking through menus.

What you can say

"What's on my currently reading list?"

"Add Project Hail Mary to my library as currently reading"

"Search for books by Brandon Sanderson"

"Look up ISBN 9780547928227"

"Create a list called 'Summer Reading' and add The Hobbit to it"

"Show me the Stormlight Archive series in reading order"

"Move Project Hail Mary and The Martian to currently reading"

"What books has Andy Weir written? Add any I haven't read to my want-to-read list"

"Compare my rating of Dune with the Hardcover average"

What's covered

  • Library tracking — status, ratings, reading dates
  • List management — create, edit, add/remove books
  • Discovery — search books, authors, series, editions, and more
  • Account info — your profile and reading stats

Safety & control

  • You control your API key — it stays on your machine, never shared with third parties
  • Runs locally through your MCP client — no external server involved
  • Actions only happen when explicitly requested — nothing runs in the background
  • You review prompts and outputs in your client before anything is sent
  • Read-only mode — set HARDCOVER_READ_ONLY=true to hide every tool that can change your account (see Configuration)
  • Least-privilege keys — give the key only the scopes you need; a read-only key makes Hardcover itself refuse writes (see API key and scopes)

Quick Start

  1. Install uv (a fast Python package runner — the setup takes seconds).
  2. Create an API key at hardcover.app/account/api; see API key and scopes for links that pre-select the right scopes.
  3. Add the config below to your MCP client — no manual install needed, uvx handles it.

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "hardcover": {
      "command": "uvx",
      "args": ["hardcover-mcp"],
      "env": {
        "HARDCOVER_API_TOKEN": "<your token>",
        "HARDCOVER_TOOLSETS": "all",
        "HARDCOVER_READ_ONLY": "false"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "hardcover": {
      "command": "uvx",
      "args": ["hardcover-mcp"],
      "env": {
        "HARDCOVER_API_TOKEN": "<your token>",
        "HARDCOVER_TOOLSETS": "all",
        "HARDCOVER_READ_ONLY": "false"
      }
    }
  }
}

HARDCOVER_TOOLSETS and HARDCOVER_READ_ONLY are optional and shown with their defaults; see Configuration.

API key and scopes

Hardcover API keys carry scopes that limit what the key can do. Create a key with only the scopes this server needs (the links open Hardcover's key form with them pre-selected):

Toolset Scopes needed
core read:catalog, read:library, read:me, read:social, read:users
catalog read:catalog, read:vibes
library read:catalog, read:goals, read:library, read:lists, read:me, write:goals, write:library, write:reviews
lists read:lists, read:me, write:lists
journal read:journal, read:me, write:library
social read:me, read:prompts, read:social, read:users, write:prompts, write:social

read:me is needed almost everywhere because tools look up who you are first. write:reviews is only needed to write or edit a review with set_user_book; without it, status, rating, and notes changes still work. If you only load some toolsets (see Configuration), the key only needs those rows plus core.

  • Keys created before August 2026 have full access and keep working.
  • When you create a key, Hardcover asks for an expiry date. After it, every tool returns "Hardcover rejected the API token … expired" with a link to create a new one.
  • If a tool needs a scope your key lacks, its error names the missing scopes and links to a key form with them pre-selected.

Configuration

Optional environment variables, set in the same env block as your token:

Variable Default Effect
HARDCOVER_TOOLSETS all Comma-separated toolsets to load. Fewer tools means less context used and fewer wrong tool picks.
HARDCOVER_READ_ONLY false true hides every tool that creates, changes, or deletes anything.
Toolset What it covers
core Always loaded: search_books, get_user
catalog Books (with characters and editions), editions, authors, series, publishers, trending, vibes
library Your library, reading dates and progress, ownership, reviews, stats, goals
lists Viewing and managing your lists
journal Reading journal notes and quotes
social Activity feed, following users, community prompts

For example, a read-only assistant for browsing books and your own library:

"env": {
  "HARDCOVER_API_TOKEN": "<your token>",
  "HARDCOVER_TOOLSETS": "catalog,library",
  "HARDCOVER_READ_ONLY": "true"
}

An unknown toolset name stops the server at startup with a message listing the valid names.

Tools

Grouped by toolset (see Configuration). Tools marked ✏️ can change your account and are hidden in read-only mode.

core (always loaded)

What you can do Tool
Search for books, authors, series, lists, users, and more (with sort/filter) search_books
See your profile and reading stats, or look up another user; optionally with library, followers, and following get_user

catalog

What you can do Tool
Look up a book by ID or slug (optionally with its characters and editions), or a specific edition by ISBN, ASIN, or edition ID get_book
Browse an author's catalogue get_author
Explore a series in reading order get_series
Look up a publisher and its editions get_publisher
See what's trending now get_trending_books
Browse curated recommendation collections (vibes) get_vibes

library

What you can do Tool
Browse your library: filter by status, date range, reviewed or owned books; sort by rating/date get_user_library
Check your status, rating, review, and reads for one book get_user_book
Get your active reading goals and progress get_reading_goal
✏️ Add a book or update its status, rating, review, notes, privacy, edition, and ownership set_user_book
✏️ Log or edit reading dates and progress (pages, audiobook time) set_user_book_read
✏️ Create, update, or archive a reading goal (books/pages, date range) set_reading_goal
✏️ Delete a reading goal delete_reading_goal
✏️ Remove a reading entry or a whole book delete_user_book_read / delete_user_book

lists

What you can do Tool
View your lists, or one list with its books get_list
✏️ Create or rename a list, or change its privacy set_list
✏️ Add or remove a book on a list set_list_book
✏️ Delete a list delete_list

journal

What you can do Tool
Read your journal entries (notes, quotes, status events) get_reading_journal
✏️ Add or edit a journal note/quote set_journal_entry
✏️ Delete a journal entry delete_journal_entry

social

What you can do Tool
See recent activity from people you follow (or one user) get_activity_feed
✏️ Follow or unfollow a user set_following
Browse community book prompts get_prompts
✏️ Answer a prompt with a book, or withdraw the answer set_prompt_answer

Development

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

Lint and format checks (using Ruff):

uv run ruff check src/
uv run ruff format --check src/

Run tests:

uv run pytest tests/ -v

Integration Tests

Integration tests hit the live Hardcover API and require a valid token. They are skipped automatically in CI and when the token is absent.

To run them locally, create a .env file with your token:

HARDCOVER_API_TOKEN=your_token_here

Then run:

uv run pytest tests/integration/ -v

Write tests follow a create → verify → delete lifecycle so the account is left unchanged.

Contributing

Contributions are welcome! Please:

  1. Open an issue first to discuss the change.
  2. Fork the repo and create a branch (feature/short-description or fix/short-description).
  3. Run lint and tests before submitting:
    uv run ruff check src/
    uv run ruff format --check src/
    uv run pytest tests/ -v
    
  4. Keep PRs focused — one change per PR.
  5. Use conventional commit prefixes: feat:, fix:, chore:, docs:.

Rate Limiting

The Hardcover API allows 60 requests per minute with a short burst allowance, and a daily limit (5,000 requests on the free plan). The server queues requests, follows the API's rate-limit headers, and retries when asked to wait. Once the daily limit is used up it stops immediately with a message saying so (it resets at midnight UTC). Your usage is shown at hardcover.app/account/api. Keys created after August 2026 get twice the burst allowance of older keys.

Troubleshooting

Problem Fix
"API token is not set" Add your token to the config (see Quick Start above)
"Hardcover rejected the API token" The key is invalid or expired; create a new one with the link in the error
"missing the scope(s) this tool needs" Create a key that includes them; the error links to a pre-filled form
"daily API limit … is used up" Wait until midnight UTC, or load fewer tools to make fewer calls
"Access is denied" on Windows Add "UV_LINK_MODE": "copy" to the env block in your config
Slow or repeated errors The server retries automatically — wait a moment and try again
Unexpected results Check for a newer version: the Hardcover API may have changed

Disclaimer

Unofficial project. Not affiliated with Hardcover.

Metadata

Release files for hardcover-mcp 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hardcover-mcp 0.9.0
File Size Uploaded Provenance Actions
hardcover_mcp-0.9.0.tar.gz 50.5 kB With provenance Details for hardcover_mcp-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hardcover-mcp 0.9.0
File Interpreter ABI Platform Actions
hardcover_mcp-0.9.0-py3-none-any.whl Python 3 none any Details for hardcover_mcp-0.9.0-py3-none-any.whl

Total release size: 116.1 kB

Release files / hardcover_mcp-0.9.0.tar.gz

Download URL hardcover_mcp-0.9.0.tar.gz
Size 50.5 kB
Tags Source
SHA-256 checksum
How to use checksums
1532d94e921f2c17244d3eaa02f5c22081816e55affc02e1f3a478f2b1437401
BLAKE2b-256 checksum
How to use checksums
a28ba2deab9a819790868de6b399c6f96a56d77017901c04898d98dee039b41c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / hardcover_mcp-0.9.0-py3-none-any.whl

Download URL hardcover_mcp-0.9.0-py3-none-any.whl
Size 65.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4a84e9f33c718d7f778ac2f19c7ce08de8249ea90ec597430610f7944458357d
BLAKE2b-256 checksum
How to use checksums
52deb2aa42375496d505edb5d895f1e6ed379b8be65eb5e25bd000d0890a390e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Security for hardcover-mcp 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hardcover_mcp-0.9.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page