Hardcover

MCP Server to fetch Books, Book Series, and User Books from Hardcover

GitHub

Hardcover MCP

A Model Context Protocol (MCP) server that exposes read-only access to the Hardcover.app GraphQL API. Tools are namespaced under books.*, users.*, and series.*, with resources and prompts to guide safe, low-volume querying.

This is an unofficial, community-maintained server and is not affiliated with Hardcover.app.

Requirements

Installation

# Option A: with uv (recommended)
uv pip install -e .

# Option B: with pip
python -m venv .venv
source .venv/bin/activate
pip install -e .

Transport Protocol

This server currently only supports STDIO as the transport protocol

Usage

  1. Get an API key from https://hardcover.app/account/api. Copy the value exactly as provided (it already starts with Bearer ).
  2. Export it for the server:
export HARDCOVER_API_KEY="Bearer <your-token>"

Running the server directly

  1. Start the MCP server:
uv run src/hardcover_mcp/main.py

Configuring STDIO for a AI chat

Codex

[mcp_servers.hardcover_mcp]
command = "uv"
args = ["run", "src/hardcover_mcp/main.py"]
env = { "HARDCOVER_API_KEY" = "API KEY heRE" }
cwd = "full_path_to/hardcover_mcp"

The server registers the books.*, users.*, and series.* tool namespaces, plus resources like hardcover/tag-categories and usage prompts such as hardcover/fantasy-this-year.

Running the test suite

pytest

Troubleshooting

  • HARDCOVER_API_KEY environment variable is required: ensure the variable is set in the same shell you start the server. Include the leading Bearer prefix.
  • Hardcover API returned an error response or 401/403: confirm the token is valid and not expired.
  • Slow responses or timeouts: reduce limit/offset arguments; the API enforces rate limits. Start with limit<=10.
  • SSL/HTTP transport issues: check local network/proxy settings and retry with a stable connection.

Máy chủ liên quan