
openlibrary-mcp-server
io.github.cyanheads/openlibrary-mcp-server
Search books and authors, fetch editions, browse subjects, and resolve cover images.
Documentation
@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.
Overview
Open Library's catalog of 20M+ books, editions, authors, and subjects, plus full-text search inside Internet Archive's scanned books. Search and browse, drill from a work into its editions or an author into their works, and construct cover image URLs.
Tools
| Tool | Description |
|---|---|
openlibrary_search_books | Catalog search with field filters (title, author, subject, publisher, ISBN, language), a provider-selected edition, 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, print run details, and edition-level credits (subtitle, by-statement, translators and other contributors) |
openlibrary_get_edition | Resolve up to 50 distinct identifiers per call by ISBN-10, ISBN-13, OCLC, LCCN, or Open Library Edition ID (OL…M), reporting misses and unprocessed identifiers |
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 |
Resources
| Resource | Description |
|---|---|
openlibrary://works/{work_id} | Work detail by Open Library Work ID — title, description, subjects, cover IDs, and author IDs as injectable context |
openlibrary://authors/{author_id} | Author detail by Open Library Author ID — name, bio, dates, photo IDs, and linked external identifiers as injectable context |
Both resources mirror data also available via openlibrary_get_work and openlibrary_get_author — useful for clients that don't surface MCP resources.
Agent skill
openlibrary-guide covers edition selection, bibliography resolution, passage identification, and incomplete metadata. It is included in npm, Docker, and desktop bundles and served through MCP skill discovery and skill:// resources.
Capability reference
Paginated tools return at most 1,000 rows per call, except openlibrary_search_inside at 100. Larger positive integer limits are clamped with a notice showing the applied limit and, when a later page exists, the next offset. OPENLIBRARY_CLAMP_LIMITS=false restores schema rejection above 100 rows. Text and structured output carry the same complete domain data, including arrays and numeric precision.
openlibrary_search_books tool
- Free-text query with Solr field prefixes (
title:,author:,subject:,publisher:,isbn:,language:, plusia:<ia_identifier>,author_key:<author_id>,first_publish_year:[1900 TO 1950],ebook_access:public) or dedicated filter parameters; 1–1000 results per page (default 10), offset pagination - A search needs at least one non-blank
query,title,author,subject,publisher, orisbn; blank criteria count as absent, andlanguageorsortalone fails asno_search_criteriabefore any request sort:relevance(default),new,old,rating,editionslanguageaccepts a 3-letter MARC code, an ISO 639-2/T code (deu,fra, …) in any case, or a translatable 2-letter ISO code; a code that is neither a MARC code nor an Open Library language record fails asunknown_language_coderather than silently matching nothing. Chinese is indexed under bothchiandcmninclude_availabilityadds live Internet Archive borrow/read status, off by default, at the cost of one additional search request per 100 returned works with an Internet Archive scan; flags Open Library leaves out are omitted rather than reported asfalse, andavailability: nullmeans none was returned for the work. A lookup that does not complete never fails the search: those works readnulland the notice names them as unknown- Returns work-level records with edition counts, cover IDs, subjects, and Internet Archive identifiers
- Optional
matching_editionandmatching_edition_countpreserve the Search API's selected edition and matching count. The selected edition is provider-ranked; it does not prove that every unfielded search term matches that edition invalid_search_queryreports upstream HTTP 422 validation with recovery guidance
openlibrary_get_work tool
- Fetch by Open Library Work ID (OL…W), optionally
/works/-prefixed; anything else — an ISBN, an edition or author OLID — fails input validation before any request, namingopenlibrary_get_edition(id_type: "isbn") as the route from an ISBN to its work - Returns title, description, subjects (plus place/time/people breakdowns), cover IDs, and author IDs — no author names (use
openlibrary_get_authororopenlibrary_search_books) - A merged work ID stays reachable — the redirect chain is followed to the canonical record,
work_idreports the canonical ID, and an enrichment notice names both IDs when they differ not_foundwhen the Work ID doesn't exist or its redirect chain reaches no work
openlibrary_get_editions tool
- List editions of a work by Work ID (OL…W), optionally
/works/-prefixed; 1–1000 per page (default 10), offset pagination, with the requestedoffsetechoed in the output; an offset at or past the total returns an empty page with a notice naming the last offset that returns a result - Same
work_idvalidation asopenlibrary_get_work— an ISBN resolves to its work throughopenlibrary_get_edition(id_type: "isbn") - Returns ISBN-10/13, publishers, languages, page count, cover IDs, and edition OLIDs (OL…M), plus
physical_format,edition_name, and the edition-level creditssubtitle,by_statement,contributors(name and role),contributions(legacy credit strings), andtranslated_from(MARC language codes) when recorded, all verbatim - A merged work ID stays reachable — the editions of the canonical work come back under its ID in
work_id, with an enrichment notice naming both IDs; a live work costs one request not_foundwhen the Work ID doesn't exist or its redirect chain reaches no work
openlibrary_get_edition tool
- Accepts 1–1,000 input strings, deduplicates exact strings, and processes the first 50 distinct identifiers in one upstream batch; the remainder is returned as
unprocessedfor resubmission. Every identifier shares oneid_type:isbn(10 or 13 digits, an ISBN-10 may end in anXcheck digit),oclc(numeric),lccn(any non-blank string), orolid(OL…M). WithOPENLIBRARY_CLAMP_LIMITS=false, the input array is limited to 50 entries - Partial success: identifiers that resolve return in
editions(request order), each row carrying itsidentifierexactly as supplied; the rest land inunresolvedwithinvalid_identifier(malformed or blank, never sent upstream) ornot_found(well-formed, no record) — the call fails only when nothing resolves upstream_unavailable(retryable) when Open Library's batch lookup itself fails — an HTTP error status other than a rate limit, or an HTML page or other body that is not JSON — so an upstream outage never reads as a missing edition- Authors come inline — the edition's own credits, or ones marked
source: "work"recovered from the parent work when the edition itself lists none; if those lookups fail, the batch still returns, and an enrichment notice names the editions whose authors are missing or shown by ID - Returns ISBN-10/13, OCLC, LCCN, LC call numbers, publishers, all cataloged
languages, page count, cover IDs, parent work ID, and an Internet Archiveebook_urlwhen one exists. The singularlanguageremains the first cataloged language;physical_format,edition_name, and the creditssubtitle,by_statement,contributors,contributions, andtranslated_frompreserve the catalog's wording when present - If no processed identifier resolves, the typed error also carries every
unprocessedidentifier in its data and recovery hint
openlibrary_search_authors tool
- Search by name — partial and alternate names match; 1–1000 per page (default 10), offset pagination; a blank query fails as
no_search_criteria - Returns Author ID (OL…A), alternate names, birth/death dates, top work, work count, top subjects, and average rating
openlibrary_get_author tool
- Fetch by Author ID (OL…A, in any case — it is upper-cased before the request); a leading
/authors/prefix is stripped - Returns bio, birth/death dates, photo IDs, and linked identifiers (Wikidata, VIAF, ISNI, Goodreads, LibraryThing)
- A merged author ID stays reachable — the response is the canonical record, and an enrichment notice names the canonical ID when it differs from the one requested
not_foundwhen the Author ID doesn't exist, names a record that is not an author (a work or edition OLID), or its redirect chain reaches no author
openlibrary_get_author_works tool
- List works by Author ID (OL…A, in any case); 1–1000 per page (default 20), offset pagination, with the requested
offsetechoed in the output; an empty page with a positive total carries a past-end notice - Returns title, first-publish date, cover IDs, and Work ID (OL…W) per work; for an author's works ranked by edition count, use
openlibrary_search_bookswith queryauthor_key:<author_id>and sorteditions - A merged author ID stays reachable — an enrichment notice names the canonical ID when it differs from the one requested
not_foundwhen the Author ID doesn't exist, names a record that is not an author (a work or edition OLID), or its redirect chain reaches no author
openlibrary_get_subject tool
- Subject name is trimmed, lowercased, and normalized from whitespace to underscores; 1–1000 per page (default 12), offset pagination, with the requested
offsetechoed in the output; an offset at or past the total carries a past-end notice - A
place:,person:, ortime:prefix browses a place, person, or period, taking a value fromopenlibrary_get_work'ssubject_places,subject_people, orsubject_timesverbatim (place:London (England)); whitespace after the prefix is dropped - Blank input fails as
invalid_subjectbefore any request - Returns canonical subject name, normalized subject key,
subject_type(place,person,time, orsubject), total work count, and per-work author names, edition count, and cover ID - Empty results carry a recovery notice suggesting a different word form, synonym, or broader term — subject tags are user-contributed and inconsistent
openlibrary_search_inside tool
- Full-text search across Internet Archive's scanned book text — the only tool that answers "which book contains this passage?"; quote a phrase for an exact match, unquoted terms match independently
- Usually takes 10–30 s against the live index, far above the metadata tools — reach for it deliberately, not as a general book search
- 1–100 results per page (default 10), offset pagination; each result carries a relevance score comparable only within its own result set. The full-text index serves only its first 10,000 results: a page that would run past them is shortened with a notice, and an offset of 10000 or more fails as
offset_past_result_window. A blank query fails asno_search_criteria - Results key on Internet Archive
ia_identifier, not Open Library work IDs — pass it toopenlibrary_search_booksas queryia:<ia_identifier>to reach the work and, inmatching_edition, the edition holding that scan upstream_unavailable(retryable) when the index answers without a result set, so a failed search never reads as "no book contains this"
openlibrary_get_cover_url tool
- Resolves a cover or author-photo URL from
id(numeric),isbn(10 or 13 digits, an ISBN-10 may end in anXcheck digit), orolid(OL…M fortarget: "book", OL…A fortarget: "author", in any case — the URL carries it upper-cased);sizeisS/M/L(defaultM) - Identifiers are validated locally before any request — path separators,
.., and control characters fail asinvalid_identifier, and an author lookup byisbnfails asinvalid_target - The tool constructs the URL without fetching it; a returned URL does not verify that a cover exists
- Output URL is ready to embed directly as

openlibrary://works/{work_id} resource
- Same fields as
openlibrary_get_work, as injectableapplication/jsoncontext for a conversation about a specific book - A work-OLID-shaped
work_idin any case is upper-cased before the request work_idcomes fromopenlibrary_search_booksoropenlibrary_get_author_works; a merged ID resolves to the canonical work, whose ID the returnedwork_idcarries, and an ID that is not a work (an edition or author OLID) is not found
openlibrary://authors/{author_id} resource
- Same fields as
openlibrary_get_author, as injectableapplication/jsoncontext for a conversation about a specific author - An author-OLID-shaped
author_idin any case is upper-cased before the request author_idcomes fromopenlibrary_search_authors; a merged ID resolves to the canonical author, whose ID the returnedauthor_idcarries, and an ID that is not an author (a work or edition OLID) is not found
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
Open Library-specific:
- Open Library Search, Search Inside (full-text), Books, Authors, and Subjects APIs, cover URL construction, and Internet Archive availability lookups
- Work → editions and author → works drill-down, with explicit OLID cross-links between tool outputs
- Configurable
User-Agentheader (OPENLIBRARY_USER_AGENT) identifying the server per Open Library's bot-blocking convention - Batch edition resolution — up to 50 ISBN/OCLC/LCCN/OLID identifiers in one upstream call, with per-identifier partial-failure reporting
- Timeouts sized per endpoint class (10 s record lookups, 30 s searches, 45 s full-text) inside a 50 s retry budget, so a slow upstream is waited on and a failing one returns a classified error before a typical 60 s client timeout; gateway errors are not retried in a loop
Agent-friendly output:
- Recovery guidance on every empty result — echoes the search criteria and suggests how to broaden a query or which offset to retry
- Merged-record disclosure —
openlibrary_get_author,openlibrary_get_author_works,openlibrary_get_work, andopenlibrary_get_editionsfollow merge redirects and surface the canonical ID via an enrichment notice when a requested ID was merged - Per-item partial failure —
openlibrary_get_editionreturns resolved editions alongside typedunresolvedreasons instead of failing the whole batch - Complete text and structured output, with clamp and recovery notices preserved on both surfaces
Getting started
Add the hosted server to Claude Code — no API key required:
claude mcp add --transport http openlibrary-mcp-server https://openlibrary.caseyjhand.com/mcp
Or run it locally:
claude mcp add openlibrary-mcp-server -- npx -y @cyanheads/openlibrary-mcp-server
For other clients, add this to the MCP config file:
{
"mcpServers": {
"openlibrary-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/openlibrary-mcp-server"]
}
}
}
For Docker or a source build, see Running the server.
Configuration
| 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_SESSION_MODE | HTTP session posture: stateless, stateful, or auto. Overrides the stateless declared in src/index.ts. | stateless |
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 casey@caseyjhand.com |
OPENLIBRARY_CLAMP_LIMITS | Clamp page limits to each page tool's ceiling (1,000 rows; 100 for openlibrary_search_inside) and process the first 50 distinct edition identifiers, returning the remainder. false restores strict input bounds of 100 rows and 50 raw identifiers. | true |
OTEL_ENABLED | Enable OpenTelemetry | false |
See .env.example for the full list of optional overrides.
Running the server
Local development
Requires Bun v1.4.4 or higher (or Node.js ≥ 24.0.0).
-
Clone and install:
git clone https://github.com/cyanheads/openlibrary-mcp-server.git cd openlibrary-mcp-server && bun install cp .env.example .env # optional overrides; no required variables -
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 # Lint, format, typecheck, security bun run test # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec
Docker
docker run --rm -p 3010:3010 ghcr.io/cyanheads/openlibrary-mcp-server:latest
The image defaults to HTTP transport, stateless session mode, and logs to /var/log/openlibrary-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/openlibrary-mcp-server:latest"]. To build locally, run docker build -t openlibrary-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
Project structure
| Directory | Purpose |
|---|---|
src/index.ts | createApp() entry point — registers tools and resources. |
src/config | Server-specific environment variable parsing and validation with Zod. |
src/mcp-server/tools | Tool definitions (*.tool.ts) — ten tools across Search, Books, Authors, Subjects, and Covers. |
src/mcp-server/resources | Resource definitions (*.resource.ts) — Work and Author. |
src/services/open-library | Open Library service layer — API client and domain types. |
skills/ | Published agent guidance, also served through MCP skill discovery. |
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/catchin tool logic - Use
ctx.logfor logging,ctx.statefor storage - Register new tools and resources in the
createApp()arrays - Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Contributing
Issues 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-servernpm install @cyanheads/openlibrary-mcp-server@cyanheads/openlibrary-mcp-servernpm install @cyanheads/openlibrary-mcp-serverRemote
Related Servers
io.github.cyanheads/anime-mcp-server
Search anime/manga, franchise relations, schedule, characters, rankings, studio filmography.
io.github.cyanheads/art-institute-chicago-mcp-server
Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides.
io.github.cyanheads/arxiv-mcp-server
Search arXiv, fetch paper metadata, and read full-text content.