@cyanheads/openlibrary-mcp-server

Public Hosted Server: https://openlibrary.caseyjhand.com/mcp

Tools

10 tools for working with Open Library's catalog of 20M+ books, editions, authors, and subjects:

openlibrary_search_books

Full-text book search across Open Library works.

• Free-text query with Solr field prefixes: title:, author:, subject:, publisher:, isbn:, language:

• Dedicated filter parameters for title, author, subject, publisher, ISBN, and language

• Sort by relevance, newest, oldest, community rating, or edition count

• Pagination via offset for paging through large result sets

• Optional live reading availability from Internet Archive (borrow/browse/read status) — adds ~200ms latency; off by default

• Returns work-level records with edition counts, cover IDs, Internet Archive identifiers, and e-book access status

openlibrary_get_work

Fetch a work by Open Library Work ID (OL…W).

• Title, description, subjects, cover IDs, and linked author IDs

• Works represent the abstract book concept independent of any specific edition

• Author names are not included — use openlibrary_get_author or openlibrary_search_books for names

openlibrary_get_editions

List editions of a work — different publishers, languages, formats, and print runs.

• Returns ISBNs, publisher, language, page count, and edition OLIDs

• Pagination via offset

• Use after openlibrary_get_work or openlibrary_search_books to find a specific printing

openlibrary_get_edition

Resolve one or more editions by identifier.

• Accepts ISBN-10, ISBN-13, OCLC, LCCN, or Open Library Edition ID (OL…M)

• Takes 1–50 identifiers per call, all of the same id_type, resolved in a single upstream request — a bibliography or shelf export costs one call rather than one per book

• Pass id_type "isbn" for both ISBN-10 and ISBN-13

• Returns full edition metadata: authors, publisher, language, all identifier types, and the parent work ID

• Partial success: identifiers that resolve come back in editions, the rest in unresolved with a reason (invalid_identifier for a value that cannot be the given type, not_found for one Open Library holds no record for). The call fails only when nothing resolved

openlibrary_search_authors

Search Open Library authors by name.

• Partial names and alternate names work

• Returns Open Library Author IDs, names, birth/death dates, top works, and subject associations

• Use author IDs for openlibrary_get_author (bio, remote IDs) or openlibrary_get_author_works (list of works)

openlibrary_get_author

Fetch author detail by Open Library Author ID (OL…A).

• Bio, birth/death dates, photo IDs

• Linked external identifiers: Wikidata, VIAF, ISNI, Goodreads, and LibraryThing

• Use openlibrary_search_authors to find an author ID first

openlibrary_get_author_works

List works by an author.

• Returns titles, cover IDs, and Work OLIDs for drilling into editions or details

• Use openlibrary_get_author for author bio and details, or openlibrary_get_editions to explore specific printings

openlibrary_get_subject

Browse works by subject tag.

• Returns matching works with edition counts and cover IDs, plus the total work count for the subject

• Subjects are user-contributed and may be inconsistent ("science fiction", "Science fiction", "SF" are separate tags)

• Try lowercase forms first

openlibrary_search_inside

Full-text search inside books scanned by the Internet Archive.

• Answers "which book contains this passage?" — the one question the metadata tools cannot

• Quote a phrase for an exact-phrase match; unquoted terms match independently

• Returns Internet Archive items with the matching passages as snippets and a relevance score

• Snippets are capped in the text output and complete in structuredContent, with the omitted count disclosed

• Seconds-slow against the live index, an order of magnitude above the metadata endpoints — reach for it deliberately

• Results key on Internet Archive items, not Open Library works: match the returned ia_identifier against the ia_identifiers on openlibrary_search_books results to reach the catalogue record

openlibrary_get_cover_url

Resolve a cover image URL for a book or author photo.

• Returns a direct HTTPS URL in the requested size (S/M/L)

• URLs can be embedded in markdown as ![cover](url)

• The Covers API always returns HTTP 200 — missing covers return a 1×1 placeholder GIF, not a 404, so the identifier format is validated locally first: id must be numeric, isbn 10 or 13 digits, olid an edition OLID (OL…M) for target book and an author OLID (OL…A) for target author

Related MCP server: kiwix-mcp

Resources

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation

• Unified error handling across all tools

• Pluggable auth (none, jwt, oauth)

• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Structured logging with optional OpenTelemetry tracing

• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

Open Library-specific:

• Complete Open Library REST API integration — Search API, Search Inside (full-text) API, Books API, Authors API, Subjects API, Covers API

• Configurable User-Agent header for well-behaved bot identification per community convention

• Work → editions → edition drill-down pattern with explicit linking between OLIDs across tools

• Internet Archive availability lookup (opt-in) for borrow/read status on search results

Agent-friendly output:

• Explicit recovery hints on empty results — echoes search criteria and suggests how to broaden

• All OLID cross-links surfaced in responses so agents can chain tool calls without re-searching

• Cover URLs rendered as embeddable markdown image syntax

Getting started

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "openlibrary-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/openlibrary-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "openlibrary-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/openlibrary-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "openlibrary-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/openlibrary-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (or Node.js ≥ 24.0.0).

• No API key required — Open Library is a free, public API.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/openlibrary-mcp-server.git

2. Navigate into the directory:

cd openlibrary-mcp-server

3. Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Running the server

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for logging, ctx.state for storage

• Register new tools and resources in the createApp() arrays

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.