hardcover-mcp

Talk to your [Hardcover](https://hardcover.app) 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.

1. 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):

<!-- scopes:start -->

• Everything: create a key with all scopes
• Read-only: create a read-only key. Pair it with HARDCOVER_READ_ONLY=true; Hardcover then refuses writes even if a tool tried one.

<!-- scopes:end -->

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:

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)

catalog

library

lists

journal

social

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

1. Keep PRs focused — one change per PR.
2. 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

Disclaimer

Unofficial project. Not affiliated with Hardcover.