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

Quick Start

1. Install uv (a fast Python package runner — the setup takes seconds).
2. Get an API token from hardcover.app/account/api.
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>"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

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

Tools

Browse & discover

Your library

Lists

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. The server handles this automatically — it queues requests and retries if needed. You shouldn't hit this in normal use.

Troubleshooting

Disclaimer

Unofficial project. Not affiliated with Hardcover.