@cyanheads/openlibrary-mcp-server

Search books and authors, fetch editions, browse subjects, and resolve cover images from Open Library via MCP. STDIO or Streamable HTTP.

10 Tools • 2 Resources

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:

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

Clone the repository:

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

Navigate into the directory:

cd openlibrary-mcp-server

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.

@cyanheads/openlibrary-mcp-server

Search books and authors, fetch editions, browse subjects, and resolve cover images from Open Library via MCP. STDIO or Streamable HTTP.

10 Tools • 2 Resources

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:

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

Clone the repository:

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

Navigate into the directory:

cd openlibrary-mcp-server

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.

openlibrary-mcp-server

@cyanheads/openlibrary-mcp-server

Tools

openlibrary_search_books

openlibrary_get_work

openlibrary_get_editions

openlibrary_get_edition

openlibrary_search_authors

openlibrary_get_author

openlibrary_get_author_works

openlibrary_get_subject

openlibrary_search_inside

openlibrary_get_cover_url

Resources

Features

Getting started

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Project structure

Development guide

Contributing

License

openlibrary-mcp-server

@cyanheads/openlibrary-mcp-server

Tools

openlibrary_search_books

openlibrary_get_work

openlibrary_get_editions

openlibrary_get_edition

openlibrary_search_authors

openlibrary_get_author

openlibrary_get_author_works

openlibrary_get_subject

openlibrary_search_inside

openlibrary_get_cover_url

Resources

Features

Getting started

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Project structure

Development guide

Contributing

License

More from cyanheads

Related Search & Web Crawling MCP Servers

More from cyanheads

Related Search & Web Crawling MCP Servers

`openlibrary_search_books`

`openlibrary_get_work`

`openlibrary_get_editions`

`openlibrary_get_edition`

`openlibrary_search_authors`

`openlibrary_get_author`

`openlibrary_get_author_works`

`openlibrary_get_subject`

`openlibrary_search_inside`

`openlibrary_get_cover_url`

`openlibrary_search_books`

`openlibrary_get_work`

`openlibrary_get_editions`

`openlibrary_get_edition`

`openlibrary_search_authors`

`openlibrary_get_author`

`openlibrary_get_author_works`

`openlibrary_get_subject`

`openlibrary_search_inside`

`openlibrary_get_cover_url`