.codex-plugin— 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>9 Tools • 2 Resources</div> </p> </div>

<div align="center">

</div>

<div align="center">

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

</div>

Tools

9 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

Fetch a single edition by identifier.

• Accepts ISBN-10, ISBN-13, OCLC, LCCN, or Open Library Edition ID (OL…M)
• 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

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_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

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, 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

1. Navigate into the directory:

cd openlibrary-mcp-server

1. 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.