Skip to main content
Glama

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

Related MCP server: booklore-mcp

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 Code

claude mcp add --scope user hardcover --env HARDCOVER_API_TOKEN=<your token> -- uvx hardcover-mcp

Replace <your token> with your Hardcover API key. --scope user makes the server available in every project; leave it out to add it to the current project only (see the Claude Code MCP documentation for scopes). Other settings from Configuration are extra --env KEY=value flags after the server name, e.g. --env HARDCOVER_READ_ONLY=true.

To keep the token off the command line, put the variables in a file (start from .env.example) and let uvx read it:

claude mcp add --scope user hardcover -- uvx --env-file /path/to/hardcover.env hardcover-mcp

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; Configuration lists every setting, including HARDCOVER_API_URL.

To keep the token out of the client config, copy .env.example to a file outside any repository (for example ~/hardcover.env), put in your token, and point uvx at it. The server never reads a .env file by itself; it only gets the variables from the file you name:

"command": "uvx",
"args": ["--env-file", "/path/to/hardcover.env", "hardcover-mcp"]

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:lists, 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.

HARDCOVER_API_URL

Hardcover's API

GraphQL endpoint to call instead, e.g. a proxy. Must be https://, since every request carries your token.

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

A few rules hold for every tool:

  • Write tools change only the fields you pass; leaving a field out or passing null keeps its current value. Clearing a field (e.g. removing a rating) isn't supported yet.

  • rating is the community rating; user_rating is yours (or, in get_user, that user's).

  • A write tool whose target doesn't exist, or isn't yours, returns an error. A read tool that finds nothing returns an empty list, or "No … found." when looking up one thing.

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, including contributors and their roles (optionally with 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, reads, and list memberships for one book (excluding the internal Owned list)

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 one list (list_id) or up to 20 lists (list_ids)

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 .
uv run ruff format --check .

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, copy .env.example to .env in the repository root and put in your token. The tests load .env (it's git-ignored); the server itself never does:

cp .env.example .env

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 .
    uv run ruff format --check .
    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. It waits at most a minute at a time; if Hardcover asks for longer, the call stops and says how long 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

"rate limit asks to wait N seconds"

Hardcover is throttling this key; try again after that time

"Hardcover didn't answer within 30 seconds"

Try again; if you asked for a change, check whether it was saved first

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

Available Tools

28 tools
delete_journal_entryA
DestructiveIdempotent

Permanently delete one of your reading journal entries by id (from get_reading_journal). Only that entry is removed; the book, its status, and other entries are unaffected. Cannot be undone. Returns {deleted: true, id}.

Inputs: id (required).

delete_listA
DestructiveIdempotent

Permanently delete a list you own by id. The books themselves stay in your library; only the list and its entries are removed. Cannot be undone. Returns {deleted: true, id}. To take a single book off use set_list_book with on_list=false.

Inputs: id (required).

delete_reading_goalA
DestructiveIdempotent

Permanently delete one of your reading goals by id (from get_reading_goal). Cannot be undone; to just hide a goal use set_reading_goal(id, archived=true). Your books and reading progress are unaffected. Returns {deleted: true, id}.

Inputs: id (required).

delete_user_bookA
DestructiveIdempotent

Permanently remove a book from your library (by book_id or user_book_id), including its status, rating, review, and private notes. Cannot be undone. Returns {deleted: true, user_book_id}. To change status instead use set_user_book; to take it off a custom list use set_list_book(on_list=false).

Inputs: book_id, user_book_id.

delete_user_book_readA
DestructiveIdempotent

Permanently delete one read entry (a single start/finish/progress record) by its user_book_read id from get_user_book. The book stays in your library with its status, rating, and review; only that read is removed. Cannot be undone. Returns {deleted: true, id}. To remove the whole book use delete_user_book.

Inputs: id (required).

get_activity_feedA
Read-only

Get recent social activity events (status changes, ratings, reviews, list updates), newest first. Read-only. Defaults to the feed of users you follow (empty if you follow nobody); pass user_id or username for one user's activity. Returns {returned, offset, activities} with event type, book, user, and timestamp per event. For your own detailed notes, quotes, and progress log use get_reading_journal; for your review texts use get_user_library(has_review=true).

Inputs: limit, offset, user_id, username.

get_authorA
Read-only

Get an author by Hardcover id, slug, or name (provide at least one; a name resolves to the top search match). Read-only. Returns bio, birth/death year, book and reader counts, and up to books_limit of their books (title, year, rating). Use search_books(query_type='Author') to compare several candidates.

Inputs: id, name, slug, books_limit.

get_bookA
Read-only

Look up a book or one specific edition of it. Read-only. With id or slug: the book (the work, across all editions) — title, authors, pages, community rating. With exactly one of isbn_13, asin, or edition_id: that specific printing, ebook, or audiobook — format, pages, audio length, release date, language, publisher, and a summary of its book. For a book, include_characters=true adds a 'characters' array in book order (id, name, slug, biography, plus 'spoiler' and 'only_mentioned' flags; don't reveal spoiler characters unless asked), and include_editions=true adds an 'editions' array, most-read first, up to editions_limit. Edition ids work with set_user_book (edition_id, owned). Use search_books first if you only have a title; for your own status/rating of the book use get_user_book.

Inputs: id, asin, slug, isbn_13, +4 more.

get_listA
Read-only

Without id: list the lists you own, most recently updated first, as {total, returned, offset, lists} (id, name, slug, description, books count, privacy; no books), paginated with limit/offset. With id: get that list (yours or another user's) including a 'books' array in list order (position, book_id, title, slug, authors), paginated with books_limit/books_offset. Read-only. Find other users' lists with search_books(query_type='List').

Inputs: id, limit, offset, books_limit, +1 more.

get_promptsA
Read-only

List community book prompts (questions like 'best sci-fi of 2025'), most answered first, paginated with limit/offset. Read-only. Set featured=true for featured prompts only. Returns {returned, offset, prompts} with id, question, description, answers_count, and books_count. Use it to browse; to find a prompt by words in its question use search_books(query_type='Prompt'). Pass a prompt id to set_prompt_answer to submit a book.

Inputs: limit, offset, featured.

get_publisherA
Read-only

Look up a publisher by Hardcover id, slug, or name (provide one; a name resolves to the top search match). Read-only. Returns name, editions count, parent publisher, and a page of its editions (the same edition fields as get_book, plus each edition's book: id, title, slug, rating, release year) via editions_limit/editions_offset.

Inputs: id, name, slug, editions_limit, +1 more.

get_reading_goalA
Read-only

Get your active (non-archived) reading goals, soonest end date first. Read-only. Returns {returned, offset, goals} with each goal's id, target, metric (book/page), progress, date range, privacy, and state; 'goals' is empty if you have none. To create or change or archive a goal use set_reading_goal; to delete one use delete_reading_goal.

Inputs: limit, offset.

get_reading_journalA
Read-only

Get your own reading journal, newest first: notes, quotes, status changes, ratings, reviews, and progress updates. Read-only. Filter by book_id and/or event type; paginate with limit/offset. Returns {returned, offset, entries}; each entry has its id, event, text, timestamp, privacy, and book. This is your personal log; for what people you follow are doing use get_activity_feed; for review texts use get_user_library(has_review=true).

Inputs: event, limit, offset, book_id.

get_seriesA
Read-only

Get a book series by id, slug, or name (provide one; a name resolves to the top search match). Read-only. Returns series info (authors, books count, completed flag) and all its books in reading order with position, title, release year, and rating. Use search_books(query_type='Series') if a name might be ambiguous.

Inputs: id, name, slug.

get_userA
Read-only

Get a Hardcover user's profile. With no arguments, returns your own profile (the owner of the API token) including your user id; otherwise look someone up by id, username, or name (name resolves to the top search match). Read-only. Returns bio, book/follower counts, and privacy. Optional sections: include_library (recent library entries, each with the book's community 'rating' and the user's own 'user_rating'; a private user's comes back empty unless you follow them), include_following / include_followers (who they follow / who follows them, newest first), and include_stats (your own profile only: totals per status, average rating, books read in stats_year, default this year). For activity use get_activity_feed; to follow someone use set_following. Fails if the token is missing or invalid.

Inputs: id, name, username, stats_year, +7 more.

get_user_bookA
Read-only

Get your own library entry for one book: pass book_id or slug (book_id wins if both are given). Read-only. Returns user_book_id, status, user_rating (your rating), privacy, review, private notes, chosen edition, and every read entry (with their ids, needed by set_user_book_read/delete_user_book_read), plus the lists of yours it's on (not Owned; change them with set_list_book). Returns 'Book not in your library' if you haven't added it, or 'No book found with slug …' for an unknown slug. This is your relationship to the book; for the book itself (description, pages, community rating) use get_book, and to browse many of your books use get_user_library.

Inputs: slug, book_id.

get_user_libraryA
Read-only

List books in your own library (any status), paginated with limit/offset. Read-only. Filter by status, by finished-date range (start_date + end_date), or has_review=true for books you have reviewed (adds review text, spoiler flag, and review date; newest review first). Sort by updated, rating, date_added, or reviewed. Returns user_book_id, book_id, title, authors, status, and user_rating (your rating) per book (with a date range, also the read's dates). E.g. sort='rating' for top-rated; a date range answers 'what did I read in May?' (always newest finish first, so it can't take sort/order). owned=true keeps only books with an edition in your Owned list (set with set_user_book); owned books that aren't in your library are not listed. Filters combine, e.g. owned=true with status='Want to Read'. For one book's full entry use get_user_book.

Inputs: sort, limit, order, owned, +5 more.

get_vibesA
Read-only

List Hardcover 'vibes': curated, themed book recommendation collections (e.g. 'Hidden Gem Fantasy'). Read-only. Only featured vibes are returned unless featured=false; paginate with limit/offset. Returns {returned, offset, vibes}; each vibe includes title, description, likes, and up to books_per_vibe books. For popularity rankings use get_trending_books; for user-made lists use get_list.

Inputs: limit, offset, featured, books_per_vibe.

search_booksA
Read-only

Full-text search across Hardcover's catalog by title, author, ISBN, or keyword; set query_type to search authors, series, lists, users, publishers, characters, or prompts instead of books. Read-only. Returns {total, returned, page, } (e.g. 'books', 'authors') with compact hits (book hits: book_id, title, authors, series; others: id, name, slug, plus type-specific fields) ranked by relevance unless 'sort' is given. Use it to discover ids, then call get_book, get_author, get_series, etc. for full details. If you already have an id, slug, or ISBN, call the matching get_* tool directly.

Inputs: query (required), page, sort, per_page, +2 more.

set_followingA
DestructiveIdempotent

Follow (following=true) or unfollow (following=false) another Hardcover user, identified by user_id or username (provide one; user_id wins if both are given). Idempotent: if you already are in the requested state nothing changes. Followed users' activity appears in get_activity_feed. Returns user_id, following, and 'changed' (whether anything was done); an unknown user is an error.

Inputs: following (required), user_id, username.

set_journal_entryA
Destructive

Add a note or quote to your reading journal (omit id; book_id, entry, and event required) or edit one of your existing notes/quotes (pass its id from get_reading_journal; only the fields you pass change, the book can't). New entries are public unless privacy says otherwise. Each create makes a separate entry. Status, rating, and progress entries can't be created or edited here; they come from set_user_book and set_user_book_read. Returns the entry with its id.

Inputs: id, entry, event, book_id, +2 more.

set_listA
Destructive

Create a list (omit id; name required) or change the name, description, or privacy of a list you own (pass id plus at least one field; only the fields you pass are overwritten). Creating twice makes two lists, so check get_list first. Returns the list's id, name, slug, description, and privacy. Does not change which books are on it: use set_list_book for that.

Inputs: id, name, privacy, description.

set_list_bookA
DestructiveIdempotent

Put a book on your lists (on_list=true) or take it off (on_list=false): one list with list_id (optionally at a position), or up to 20 at once with list_ids. Idempotent: lists already in the requested state don't change, and an existing entry's position is not moved. Does not touch your library or reading status (use set_user_book). With list_id returns list_id, book_id, on_list, 'changed', and list_book_id; with list_ids returns one result per list, and a list that isn't yours or fails gets an 'error' while the others still change. Find list ids with get_list (or a book's current lists with get_user_book) and book ids with search_books.

Inputs: book_id (required), on_list (required), list_id, list_ids, +1 more.

set_prompt_answerA
DestructiveIdempotent

Answer a community prompt with a book (answered=true, optionally with a description of why it fits) or withdraw that answer (answered=false). Idempotent: if you already answered the prompt with that book, nothing changes and the existing description is kept. Changes take a few seconds to show, so don't repeat a call immediately. You can answer one prompt with several different books. Returns prompt_id, book_id, answered, 'changed', and answer_id. Find prompt ids with get_prompts and book ids with search_books.

Inputs: book_id (required), answered (required), prompt_id (required), description.

set_reading_goalA
DestructiveIdempotent

Create, update, or archive a reading goal. Without id: goal, metric, start_date, and end_date are required; if an active goal with the same metric and dates exists it is updated (only the fields you pass change), otherwise a new goal is created. With id (from get_reading_goal): edit that goal, changing only the fields you pass; archived=true hides it from get_reading_goal and archived=false brings it back. Returns the goal with id, target, progress, state, and archived. To remove a goal for good use delete_reading_goal.

Inputs: id, goal, metric, privacy, +4 more.

set_user_bookA
DestructiveIdempotent

Add a book to your library or update your entry for it: status, rating, review, privacy, private notes, edition, and whether you own it. Upsert: creates the entry if the book isn't in your library yet, otherwise overwrites only the fields you pass (null leaves a field as it is; clearing one isn't supported). owned=true/false marks ownership of edition_id (or of the entry's current edition if edition_id is omitted; errors if there is none); passing edition_id also makes it the edition you're reading. Ownership changes are idempotent. Returns user_book_id, status, privacy, user_rating, edition_id, and owned/owned_changed when owned was given. Use set_user_book_read for start/finish dates and progress, set_list_book for custom lists, and delete_user_book to remove the book.

Inputs: book_id (required), owned, rating, status, +6 more.

set_user_book_readA
Destructive

Log or edit reading dates and progress (pages or audiobook seconds). With id (a user_book_read id from get_user_book): edit that read, overwriting only the fields you pass, e.g. to fix a past finish date. Without id: pass book_id or user_book_id; if the book has an unfinished read it is updated (progress, a later finish date, or the same start date), otherwise a new read is created, e.g. a re-read or a past read with its own dates. The book must already be in your library (add it with set_user_book). Returns the read entry with its id.

Inputs: id, book_id, edition_id, started_at, +4 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 28 tools

    Disambiguation5/5

    Tools are cleanly separated by resource and action, e.g. get_book vs get_user_book, get_user_library vs get_list, and get_activity_feed vs get_reading_journal. Descriptions explicitly route between near-neighbors, so no two tools appear to do the same job.

    Naming Consistency5/5

    All names use snake_case with a predictable verb_noun shape: get_*, set_*, delete_*, and search_*. The broad use of set_ for create/update/upsert is applied consistently across the server.

    Tool Count3/5

    At 28 tools, the surface is heavy, but it spans many Hardcover subdomains: catalog, library, reads, goals, lists, journal, social, prompts, and discovery. Most tools cover distinct operations, so it is borderline rather than clearly bloated.

    Completeness4/5

    CRUD/lifecycle coverage is strong for library entries, reads, goals, lists, and journal entries, with discovery and social flows also represented. Minor gaps remain, such as reordering existing list books or editing prompt-answer descriptions, and no standalone character/edition retrieval beyond embedded options.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    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.
      -
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to interact with BookLore self-hosted libraries, allowing natural language queries to search books, manage reading status, ratings, series, authors, and highlights.
      7
      1
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP-compatible AI assistants to search the Hardcover book catalogue and manage personal library data, reading progress, reading statistics, goals, activities, and more through natural language.
      25
      1
      MIT