hardcover-mcp
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=trueto 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
- Install uv (a fast Python package runner — the setup takes seconds).
- Create an API key at hardcover.app/account/api; see API key and scopes for links that pre-select the right scopes.
- Add the config below to your MCP client — no manual install needed,
uvxhandles 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):
- 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.
| 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:
- Open an issue first to discuss the change.
- Fork the repo and create a branch (
feature/short-descriptionorfix/short-description). - Run lint and tests before submitting:
uv run ruff check src/ uv run ruff format --check src/ uv run pytest tests/ -v
- Keep PRs focused — one change per PR.
- 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.