Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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
Quick Start
- Install uv (a fast Python package runner — the setup takes seconds).
- Get an API token from hardcover.app/account/api.
- 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>"
}
}
}
}Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"hardcover": {
"command": "uvx",
"args": ["hardcover-mcp"],
"env": {
"HARDCOVER_API_TOKEN": "<your token>"
}
}
}
}Tools
Browse & discover
| What you can do | Tool |
|---|---|
| Search for books, authors, series, and more | search_books |
| Look up a book by title or ID | get_book |
| Look up a specific edition by ISBN or ASIN | get_edition |
| Explore a series in reading order | get_series |
| Browse an author's catalogue | get_author |
Your library
| What you can do | Tool |
|---|---|
| See your profile and book count | me |
| Get reading statistics (totals, ratings, books read per year) | get_reading_stats |
| Get your active reading goals and progress | get_reading_goal |
| Browse your library, filter by status, date range, or sort by rating/date | get_user_library |
| Check your status/rating for a specific book (includes privacy setting) | get_user_book |
| List your reviews | get_user_reviews |
| Read your journal entries (notes, quotes, status events) | get_reading_journal |
| List books you own, with edition details | get_owned_books |
| Create or update a reading goal (books/pages, date range) | set_reading_goal |
| Add a book or update its status, rating, review, notes, privacy, and edition | set_user_book |
| Mark an edition as owned or not owned | set_edition_owned |
| Log reading dates and progress (pages, audiobook time) | add_user_book_read / update_user_book_read |
| Remove a book or reading entry | delete_user_book / delete_user_book_read |
| Create or delete a journal note/quote entry | add_journal_entry / delete_journal_entry |
Lists
| What you can do | Tool |
|---|---|
| View all your lists | get_my_lists |
| View a specific list with its books | get_list |
| Create, rename, or delete a list | create_list / update_list / delete_list |
| Add or remove books from a list | add_book_to_list / remove_book_from_list |
Development
git clone https://github.com/kristianedlund/hardcover-mcp.git
cd hardcover-mcp
uv syncLint and format checks (using Ruff):
uv run ruff check src/
uv run ruff format --check src/Run tests:
uv run pytest tests/ -vIntegration 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_hereThen run:
uv run pytest tests/integration/ -vWrite 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. The server handles this automatically — it queues requests and retries if needed. You shouldn't hit this in normal use.
Troubleshooting
| Problem | Fix |
|---|---|
| "API token is not set" | Add your token to the config (see Quick Start above) |
| "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.