hardcover-oauth-mcp

A remote Model Context Protocol (MCP) server for Hardcover, the book tracking site. It lets Claude and other MCP clients read and manage your library, reading progress, reviews, journal, lists, goals, and more.

• Works in web and mobile clients. The public instance is a hosted remote server, so Claude on the web and on phones, ChatGPT, and other remote clients can connect to it. Other Hardcover MCP servers run on your own computer, where only desktop clients can reach them.

• Sign in with Hardcover (OAuth). No pasting unsafe API keys. Each person connects their own account through Hardcover's OAuth and picks which permissions to grant.

• 53 read/write tools. 47 custom task-oriented tools cover the library, progress, reviews, journal, lists, goals, follows, notifications, and vibes. Six raw GraphQL and schema-discovery tools reach anything else in the Hardcover API.

Connect to the public instance at https://hardcover.benjuntilla.com/mcp (quick start) or deploy your own.

Example workflows

Track a book

1. "I'm on page 212 of Piranesi." The book moves to Currently Reading and the page goes on its reading session.

2. "Finished it today, 4.5 stars." The book moves to Read, finished today, with a 4.5-star rating.

Plan what's next

1. "Add Kindred and The Dispossessed to my want-to-read."

2. "Make a ranked list called Summer with both, Kindred first."

3. "Move The Dispossessed to the top."

Set a reading goal

1. "Set a goal of 30 books this year."

2. "How am I doing on my goal?"

Keep a journal

1. "Save this quote from Piranesi: 'The Beauty of the House is immeasurable; its Kindness infinite.'"

2. "Show my notes on Piranesi."

Pick an edition

1. "Which audiobook editions of Dune are there, and how long are they?"

2. "Switch my copy to the shortest one."

Ask anything else

1. "Which of the books I read last year had the most pages?" With no tool for that, the client looks up the API with hardcover_find_operations and runs a read-only hardcover_query.

2. "Answer the prompt 'What book made you cry uncontrollably?' with Kindred." The client finds the prompt with hardcover_search, looks up the mutation with hardcover_find_operations, and runs hardcover_mutate.

Related MCP server: hardcover-mcp

Quick start

Anyone with a Hardcover account can use the public instance. Add this URL to your MCP client as a remote server:

https://hardcover.benjuntilla.com/mcp

• Claude (web, desktop, mobile): Settings → Connectors → Add custom connector, then paste the URL.

• Claude Code: claude mcp add --transport http hardcover https://hardcover.benjuntilla.com/mcp, then run /mcp to sign in.

• ChatGPT (web, desktop, mobile): on chatgpt.com, open Plugins, select + → Add custom MCP server, paste the URL, keep OAuth as the authentication, and create it. Type @ in a chat to use it.

• Cursor and others: add a remote (Streamable HTTP) server with that URL. The client discovers OAuth by itself.

• MCP Inspector: bunx @modelcontextprotocol/inspector, choose Streamable HTTP, and enter the URL.

Your client opens a consent page where you pick permissions, then Hardcover asks you to sign in. Revoke access any time from Hardcover's Authorized apps page. See the privacy notice and terms, or deploy your own.

Report an issue

Something not working? Open an issue on GitHub, or email ben@benjuntilla.com. For security problems, follow the security policy instead.

How it works

It runs on the Cloudflare Developer Platform (Workers, Durable Objects, and KV), chosen for its convenient developer experience and cost efficiency. A Durable Object per connection holds the tokens and serves MCP; KV holds OAuth state. Alchemy deploys it in one command, and alchemy dev runs the same code locally. It's built with Effect 4 (including Effect's own MCP server), TypeScript 7, Bun, mise, and Astro.

┌──────────────┐  MCP + OAuth 2.1   ┌──────────────────────────────┐
│ MCP client   │ ─────────────────▶ │ Worker                       │
│ (Claude, …)  │ ◀───────────────── │  OAuthProvider, consent page │
└──────────────┘  MCP access token  │  auth + rate limits on /mcp  │
                                    └──────────────┬───────────────┘
                                                   │ one per connection
                                    ┌──────────────▼───────────────┐
                                    │ HardcoverConnection (DO)     │
                                    │  Hardcover tokens            │
                                    │  Effect McpServer + tools    │
                                    └──────────────┬───────────────┘
                                                   │ OAuth + GraphQL
                                    ┌──────────────▼───────────────┐
                                    │ Hardcover API                │
                                    └──────────────────────────────┘

The Worker is an OAuth authorization server for MCP clients, built on @cloudflare/workers-oauth-provider. It supports dynamic client registration and Client ID Metadata Documents.

The Worker checks each /mcp request (token, allowlist, the server's own rate limit, scopes) and forwards it to the connection's Durable Object. The object runs Effect's MCP server. It speaks the sessionless 2026-07-28 revision as well as 2025-11-25, 2025-06-18, and 2025-03-26. Sessions for the 2025 revisions live in the object's memory. When Cloudflare evicts an idle object, its sessions end: the client gets a 404 and, as the protocol requires, starts a new session.

Tools

Kinds: read, write (adds or changes data), and delete. A tool appears only if you chose its scopes for your connection.

Supporter is a paid Hardcover membership and Librarian a Hardcover librarian role. Hardcover enforces both; a tool that always needs one says so in its title and description. Sign-in drops write:catalog:edit and write:catalog:map from accounts without the role, but anyone can add catalog records with write:catalog:append.

The raw tools check each document's operation kind, root fields, needed scopes, and size (at most 10 top-level fields) before sending it. They also reject text operators Hardcover has disabled, such as _like and _regex. Mistakes come back as clear errors instead of using up your Hardcover rate limit. hardcover_find_operations and hardcover_describe_type search an index built from Hardcover's API docs. hardcover_find_operations ranks operations by how well their names and return types match, so a phrase like "add a book to a list" works. For a type name that doesn't exist, hardcover_describe_type suggests the closest ones, so UserBook points to user_books.

Hardcover's rate limits are per user, and every app shares them. Each user gets 60 requests a minute (bursts of 10, or 15 for Supporters) and 5,000 a day (50,000 for Supporters). Each top-level field costs one request.

Deploy your own

You need mise, a Cloudflare account, and a Hardcover account. A custom domain is optional; without one, the server lives at https://hardcover-oauth-mcp.<your-subdomain>.workers.dev.

1. Install

git clone https://github.com/benjuntilla/hardcover-oauth-mcp
cd hardcover-oauth-mcp
mise install
cp .env.example .env

2. Register a Hardcover app

Create one at hardcover.app/account/developer-apps/new:

• Application type: Web app (server-side). You can't change this later.

• Redirect URIs: https://<your-domain>/callback, plus http://localhost:1337/callback for local runs.

• Scopes this app may request: read:me:content read:me:roles read:catalog read:library write:library write:reviews read:journal read:lists write:lists read:goals write:goals read:users read:social write:social read:notifications write:notifications read:prompts write:prompts read:vibes write:vibes read:account write:catalog:append write:catalog:edit write:catalog:map openid offline_access. Leave all unticked, since it would also cover scopes Hardcover adds later.

• Device Authorization Grant: off.

Put the client id and secret into .env as HARDCOVER_CLIENT_ID and HARDCOVER_CLIENT_SECRET. Hardcover shows the secret only once.

3. Configure

In alchemy.run.ts, edit DEPLOYMENTS. Each key is a stage: mise run deploy --stage prod uses prod, and mise run dev uses local.

const DEPLOYMENTS: Readonly<Record<string, DeploymentSettings>> = {
  local: { allowedUsers: ["*"] },
  prod: { allowedUsers: ["your-username"], domain: "hardcover.example.com" },
}

• allowedUsers: your Hardcover username (or several, or numeric ids). Use "*" to let anyone connect, as the public instance does. Every person uses their own account and Hardcover rate limit.

• domain: a hostname on a zone in your Cloudflare account. Leave it out to use the auto-assigned workers.dev URL.

4. Sign Alchemy in to Cloudflare

bun alchemy profile edit --add Cloudflare

5. Deploy

mise run deploy --stage prod

This builds the site, creates the Cloudflare resources, and prints the URL. Run it again after changes. mise run logs --stage prod tails logs. mise run destroy --stage prod removes everything.

Deploys keep Alchemy's state in your Cloudflare account, so any machine signed in with Alchemy can redeploy or destroy. The first deploy sets up the state store there. mise run dev and the tests keep theirs in .alchemy/.

• Plan: use Workers Paid. A connection's Durable Object builds its MCP server when it wakes. That takes about 100 ms of CPU, ten times the Free plan's per-request limit. After that, a call takes about 5 ms.

• The server's own rate limits: 10 registrations, 30 sign-in steps, and 60 token requests a minute per client IP. Each Hardcover account gets 120 MCP requests a minute.

• Observability: Workers Logs, Traces, and Issues are on. Cloudflare's request logs record each request's path, status, headers, and client IP, but not its query string or body. Cloudflare redacts the authorization and cookie headers. Leaving out query strings keeps Hardcover's one-time sign-in code out of logs and traces. What the token grants reaches the Durable Object as a method argument rather than a header, so it stays out of the logs. The OAuth provider files grants under a keyed pseudonym of the Hardcover user id, so the storage keys in traces don't reveal it. The Worker logs unexpected failures (defects) without tokens or request data, and Issues groups them. Expected ones, such as Hardcover rate limits, revoked access, or bad queries, go back to the agent as tool errors.

6. Connect a client

Connect the same way as the public instance, with https://<your-domain>/mcp as the URL.

Run locally

With the app and .env from steps 1 and 2 above, the whole flow works on your machine:

1. Run mise run dev. It serves the Worker in workerd at http://localhost:1337, with local KV and Durable Objects, and reloads on code changes. It builds the static pages (README.md, PRIVACY.md, TERMS.md, SECURITY.md, and site/) once at start, so restart it to see changes to them. You don't need a Cloudflare account.

2. Connect a client on the same machine to http://localhost:1337/mcp, for example claude mcp add --transport http hardcover-local http://localhost:1337/mcp.

Development

mise run check      # format check, lint, prose lint, unused code, typecheck (bun check), and unit tests
mise run test:e2e   # the Worker in workerd, a mock Hardcover, and a scripted MCP client

• Unit tests (bun test) cover the GraphQL guard, the executor's refresh and retry rules, scope handling, and every tool. Each tool runs through the real Effect MCP server, and the tests validate its GraphQL against Hardcover's published schema (test/fixtures/hardcover-schema.graphql).

• The end-to-end test runs the Worker in workerd against a mock Hardcover, signing in and calling tools as an MCP client.

• The README tool table comes from the toolkit (mise run docs:tools), and a unit test fails when it's stale.

• The schema index behind hardcover_find_operations and hardcover_describe_type comes from Hardcover's API docs (mise run schema:sync).

• Vale lints the prose on the site's pages with its standard style, Std (mise run lint:prose).