@cyanheads/openlibrary-mcp-server

<div align="center"> <h1>@cyanheads/openlibrary-mcp-server</h1> <p><b>Search books and authors, fetch editions, browse subjects, and resolve cover images from Open Library via MCP. STDIO or Streamable HTTP.</b> <div>10 Tools • 2 Resources</div> </p> </div>

<div align="center">

</div>

<div align="center">

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

</div>

---

Tools

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

Tool	Description
openlibrary_search_books	Full-text book search with field filters (title, author, subject, publisher, ISBN, language), sort options, pagination, and optional live reading availability
openlibrary_get_work	Fetch a work by Open Library Work ID (OL…W) — title, description, subjects, cover IDs, and author IDs
openlibrary_get_editions	List editions of a work — publishers, languages, formats, ISBNs, and print run details
openlibrary_get_edition	Resolve up to 50 editions in one call by ISBN-10, ISBN-13, OCLC, LCCN, or Open Library Edition ID (OL…M), reporting per-identifier misses
openlibrary_search_authors	Search authors by name — returns Author IDs, birth/death dates, top works, and subject associations
openlibrary_get_author	Fetch author detail by Open Library Author ID (OL…A) — bio, dates, photo IDs, and linked identifiers from Wikidata, VIAF, ISNI, Goodreads, and LibraryThing
openlibrary_get_author_works	List works by an author — titles, cover IDs, and Work OLIDs for drilling into editions or details
openlibrary_get_subject	Browse works by subject tag — returns matching works with edition counts and cover IDs plus the total work count
openlibrary_search_inside	Full-text search inside the scanned text of Internet Archive books — returns matching items with snippets
openlibrary_get_cover_url	Resolve a cover image URL for a book or author photo in S/M/L size — returns a direct HTTPS URL embeddable in markdown

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

Resources

Type	Name	Description
Resource	openlibrary://works/{work_id}	Work detail by Open Library Work ID — title, description, subjects, cover IDs, and author IDs as injectable context
Resource	openlibrary://authors/{author_id}	Author detail by Open Library Author ID — name, bio, dates, photo IDs, and linked external identifiers as injectable context

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:

Variable	Description	Default
MCP_TRANSPORT_TYPE	Transport: stdio or http	stdio
MCP_HTTP_PORT	HTTP server port	3010
MCP_HTTP_ENDPOINT_PATH	HTTP endpoint path where the MCP server is mounted	/mcp
MCP_PUBLIC_URL	Public origin override for TLS-terminating reverse-proxy deployments	none
MCP_AUTH_MODE	Authentication: none, jwt, or oauth	none
MCP_LOG_LEVEL	Log level (debug, info, warning, error, etc.)	info
MCP_GC_PRESSURE_INTERVAL_MS	Opt-in Bun-only forced-GC pressure loop (ms). Recommended starting point if heap growth is observed: 60000.	0 (disabled)
LOGS_DIR	Directory for log files (Node.js only)	<project-root>/logs
STORAGE_PROVIDER_TYPE	Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1	in-memory
OPENLIBRARY_USER_AGENT	User-Agent sent with all Open Library API requests. Include a contact email per community convention.	openlibrary-mcp-server/1.0 (openlibrary@archive.org)
OTEL_ENABLED	Enable OpenTelemetry	false

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

Directory	Purpose
src/mcp-server/tools	Tool definitions (*.tool.ts). Ten tools across Search, Books, Authors, Subjects, and Covers.
src/mcp-server/resources	Resource definitions. Work and Author resources.
src/services/open-library	Open Library service layer — API client and domain types.
src/config	Server-specific environment variable parsing and validation with Zod.
tests/	Unit and integration tests, mirroring the src/ 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.