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": ""
      }
    }
  }
}

Claude Desktop

Add to `claude_desktop_config.json`:

{
  "mcpServers": {
    "hardcover": {
      "command": "uvx",
      "args": ["hardcover-mcp"],
      "env": {
        "HARDCOVER_API_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.