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

[![Version](https://img.shields.io/badge/Version-0.2.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/openlibrary-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/openlibrary-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openlibrary-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/openlibrary-mcp-server/releases/latest/download/openlibrary-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=openlibrary-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvb3BlbmxpYnJhcnktbWNwLXNlcnZlciJdfQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22openlibrary-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fopenlibrary-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

**Public Hosted Server:** [https://openlibrary.caseyjhand.com/mcp](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`](https://github.com/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 sugge