io.github.cyanheads/openlibrary-mcp-server

Official10 toolsLive

by cyanheads · TypeScript

Search books and authors, fetch editions, browse subjects, and resolve cover images.

io.github.cyanheads/openlibrary-mcp-server (MCP Server)

The Open Library MCP server provides tools to search books and authors, fetch editions, browse subjects, and resolve cover images from Open Library via MCP. It supports transport over STDIO or Streamable HTTP. The repository identifies it as a TypeScript MCP server.

🛠️ Key Features

Search books and authors
Fetch editions
Browse subjects
Resolve cover images
Offers 10 tools and 2 resources
Runs as an MCP server over STDIO or Streamable HTTP

🚀 Use Cases

Look up bibliographic records for books and authors
Retrieve edition details for ISBN-related workflows
Explore Open Library subjects
Obtain cover images for display in client applications

⚡ Developer Benefits

Standardized access via Model Context Protocol (MCP)
Tooling focused on Open Library operations (search, editions, subjects, covers)
Suitable for TypeScript integrations and agent pipelines

⚠️ Limitations

Functionality is scoped to Open Library (books/authors/editions/subjects/covers)
Exposes 10 tools and 2 resources as documented in the repository excerpt

Topics

ai-agentauthorsbooksbuneditionsinternet-archiveisbnlibrarymcpmcp-servermodel-context-protocolopen-librarytypescriptcyanheads

Captured live from the server via tools/list.

openlibrary_search_books

Full-text book search across Open Library works. Supports field filters (title, author, subject, publisher, ISBN, language) and returns work-level records with edition counts, cover IDs, and reading availability. Use query for general search or combine specific field filters. Results are work-level — drill into editions via openlibrary_get_editions.

Parameters11

query	string	optional	Full-text search query. Supports Solr field prefixes: title:, author:, subject:, publisher:, isbn:, language:. Omit to use the filter parameters instead.
title	string	optional	Filter by title. Matched against work title and alternative titles.
author	string	optional	Filter by author name. Partial names work.
subject	string	optional	Filter by subject tag (e.g., "science fiction", "history").
publisher	string	optional	Filter by publisher name. Partial names work (e.g., "Penguin").
isbn	string	optional	Find works that have editions with this ISBN (10 or 13 digits, hyphens ignored).
language	string	optional	Restrict results to one language. Takes a 3-letter MARC code (e.g., "eng", "fre", "ger", "chi") — the same vocabulary openlibrary_get_edition and openlibrary_get_editions return. A 2-letter ISO 639-1 code (e.g., "en", "fr") is accepted and translated to its MARC equivalent; an unrecognized 2-letter code is rejected rather than silently ignored. The equivalent in-query form is language:eng.
sort	string	optional	Sort order. "relevance" uses Solr scoring. "new"/"old" sort by first publish year. "rating" by average community rating. "editions" by edition count.
limit	integer	optional	Max results to return. Higher values increase response size; prefer 10–20 for exploration.
offset	integer	optional	Zero-based offset for pagination.
include_availability	boolean	optional	Include live reading availability from Internet Archive (borrow/read status). Adds ~200ms latency. Use when the user needs to know if they can read the book online.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Full-text search query. Supports Solr field prefixes: title:, author:, subject:, publisher:, isbn:, language:. Omit to use the filter parameters instead.",
      "type": "string"
    },
    "title": {
      "description": "Filter by title. Matched against work title and alternative titles.",
      "type": "string"
    },
    "author": {
      "description": "Filter by author name. Partial names work.",
      "type": "string"
    },
    "subject": {
      "description": "Filter by subject tag (e.g., \"science fiction\", \"history\").",
      "type": "string"
    },
    "publisher": {
      "description": "Filter by publisher name. Partial names work (e.g., \"Penguin\").",
      "type": "string"
    },
    "isbn": {
      "description": "Find works that have editions with this ISBN (10 or 13 digits, hyphens ignored).",
      "type": "string"
    },
    "language": {
      "description": "Restrict results to one language. Takes a 3-letter MARC code (e.g., \"eng\", \"fre\", \"ger\", \"chi\") — the same vocabulary openlibrary_get_edition and openlibrary_get_editions return. A 2-letter ISO 639-1 code (e.g., \"en\", \"fr\") is accepted and translated to its MARC equivalent; an unrecognized 2-letter code is rejected rather than silently ignored. The equivalent in-query form is language:eng.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}$"
    },
    "sort": {
      "default": "relevance",
      "description": "Sort order. \"relevance\" uses Solr scoring. \"new\"/\"old\" sort by first publish year. \"rating\" by average community rating. \"editions\" by edition count.",
      "type": "string",
      "enum": [
        "relevance",
        "new",
        "old",
        "rating",
        "editions"
      ]
    },
    "limit": {
      "default": 10,
      "description": "Max results to return. Higher values increase response size; prefer 10–20 for exploration.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset for pagination.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "include_availability": {
      "default": false,
      "description": "Include live reading availability from Internet Archive (borrow/read status). Adds ~200ms latency. Use when the user needs to know if they can read the book online.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openlibrary_search_inside

Search the full text of books scanned by the Internet Archive — the "which book contains this passage?" lookup that the metadata tools cannot answer. Quote a phrase for an exact-phrase match; bare terms match anywhere in the text. Each result is an Internet Archive item with the matching passages as snippets, plus a relevance score. The full-text index is far slower than the metadata endpoints, and a search usually takes 10–30 seconds. Use it when the passage is the question, and use openlibrary_search_books to search by title, author, or subject. Results key on Internet Archive items rather than Open Library works: chain the returned ia_identifier to archive.org, or match it against the ia_identifiers on openlibrary_search_books results to reach the catalogue record.

Parameters3

query	string	required	Text to find inside scanned books. Wrap in double quotes for an exact-phrase match (e.g., "the spice must flow"); unquoted terms match independently and return far broader results.
limit	integer	optional	Max matching items to return. Each carries its own snippets, so higher values grow the response quickly — prefer 10–20.
offset	integer	optional	Zero-based offset for pagination.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Text to find inside scanned books. Wrap in double quotes for an exact-phrase match (e.g., \"the spice must flow\"); unquoted terms match independently and return far broader results."
    },
    "limit": {
      "default": 10,
      "description": "Max matching items to return. Each carries its own snippets, so higher values grow the response quickly — prefer 10–20.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset for pagination.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openlibrary_get_work

Fetch a work by Open Library Work ID (OL…W). Returns title, description, subjects, cover IDs, and linked author IDs for follow-up lookups. Works represent the abstract book concept independent of any specific edition. A merged work ID resolves to the work it was merged into. To reach a work from an ISBN, call openlibrary_get_edition with id_type "isbn" — its work_id output is the parent work. Note: author names are not included — use openlibrary_get_author or openlibrary_search_books for names.

Parameters1

work_id

string

required

Open Library Work ID. Format: OL…W (e.g., "OL45804W"), optionally prefixed "/works/". Not an ISBN — resolve an ISBN to its work with openlibrary_get_edition (id_type "isbn").

Raw schema

{
  "type": "object",
  "properties": {
    "work_id": {
      "type": "string",
      "pattern": "^(?:\\/works\\/)?OL\\d+W$",
      "description": "Open Library Work ID. Format: OL…W (e.g., \"OL45804W\"), optionally prefixed \"/works/\". Not an ISBN — resolve an ISBN to its work with openlibrary_get_edition (id_type \"isbn\")."
    }
  },
  "required": [
    "work_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openlibrary_get_editions

List editions of a work — different publishers, languages, formats, and print runs. Returns ISBNs, publisher, language, page count, and edition OLIDs. Use after openlibrary_get_work or openlibrary_search_books to find a specific printing. A merged work ID resolves to the work it was merged into. To reach a work from an ISBN, call openlibrary_get_edition with id_type "isbn" — its work_id output is the parent work.

Parameters3

work_id	string	required	Open Library Work ID. Format: OL…W (e.g., "OL45804W"), optionally prefixed "/works/". Not an ISBN — resolve an ISBN to its work with openlibrary_get_edition (id_type "isbn").
limit	integer	optional	Max editions to return. Prefer 10–20 for exploration.
offset	integer	optional	Zero-based offset for pagination.

Raw schema

{
  "type": "object",
  "properties": {
    "work_id": {
      "type": "string",
      "pattern": "^(?:\\/works\\/)?OL\\d+W$",
      "description": "Open Library Work ID. Format: OL…W (e.g., \"OL45804W\"), optionally prefixed \"/works/\". Not an ISBN — resolve an ISBN to its work with openlibrary_get_edition (id_type \"isbn\")."
    },
    "limit": {
      "default": 10,
      "description": "Max editions to return. Prefer 10–20 for exploration.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset for pagination.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "work_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openlibrary_get_edition

Resolve one or more editions by identifier: ISBN-10, ISBN-13, OCLC, LCCN, or Open Library Edition ID (OL…M). Every identifier in a call shares one id_type — pass id_type "isbn" for both ISBN-10 and ISBN-13. Up to 50 identifiers resolve in a single upstream request, so a bibliography or shelf export costs one call rather than one per book; a large batch is a large response, so ask for what you need. Returns full edition metadata including authors, publisher, language, all identifier types, and the parent work ID, with author names inline and no secondary lookup; when the edition record itself lists no authors, they are recovered from the parent work and marked as such, and a notice names any edition whose recovery failed. Partial success is the norm — identifiers that resolve come back in editions, the rest are listed in unresolved with a reason, and the call fails only when nothing resolved.

Parameters2

identifiers	array	required	Identifiers to resolve, 1–50, all of the type named by id_type. Resolved editions come back in request order.
id_type	string	required	Identifier type shared by every entry in identifiers. "isbn" handles both ISBN-10 and ISBN-13. "olid" is the native Open Library edition ID (OL…M). Mixing types within one call is not supported — issue one call per type.

Raw schema

{
  "type": "object",
  "properties": {
    "identifiers": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "description": "One identifier value. For ISBN: 10 or 13 digits, hyphens optional — an ISBN-10 may end in an X check digit (e.g., 080442957X). For OCLC: numeric string. For LCCN: string as-is. For OLID: Open Library edition ID (e.g., OL7353617M)."
      },
      "description": "Identifiers to resolve, 1–50, all of the type named by id_type. Resolved editions come back in request order."
    },
    "id_type": {
      "type": "string",
      "enum": [
        "isbn",
        "oclc",
        "lccn",
        "olid"
      ],
      "description": "Identifier type shared by every entry in identifiers. \"isbn\" handles both ISBN-10 and ISBN-13. \"olid\" is the native Open Library edition ID (OL…M). Mixing types within one call is not supported — issue one call per type."
    }
  },
  "required": [
    "identifiers",
    "id_type"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openlibrary_search_authors

Search Open Library authors by name. 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).

Parameters3

query	string	required	Author name search query. Partial names and alternate names work.
limit	integer	optional	Max results to return.
offset	integer	optional	Zero-based offset for pagination.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Author name search query. Partial names and alternate names work."
    },
    "limit": {
      "default": 10,
      "description": "Max results to return.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset for pagination.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openlibrary_get_author

Fetch author detail by Open Library Author ID (OL…A). Returns bio, birth/death dates, photo IDs, and linked identifiers from Wikidata, VIAF, ISNI, Goodreads, and LibraryThing. Use openlibrary_search_authors to find an author ID first.

Parameters1

author_id

string

required

Open Library Author ID. Format: OL…A (e.g., "OL24638A"). A leading "/authors/" prefix is stripped if provided.

Raw schema

{
  "type": "object",
  "properties": {
    "author_id": {
      "type": "string",
      "description": "Open Library Author ID. Format: OL…A (e.g., \"OL24638A\"). A leading \"/authors/\" prefix is stripped if provided."
    }
  },
  "required": [
    "author_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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.

Parameters3

author_id	string	required	Open Library Author ID (OL…A). A leading "/authors/" prefix is stripped if provided.
limit	integer	optional	Max works to return.
offset	integer	optional	Zero-based offset for pagination.

Raw schema

{
  "type": "object",
  "properties": {
    "author_id": {
      "type": "string",
      "description": "Open Library Author ID (OL…A). A leading \"/authors/\" prefix is stripped if provided."
    },
    "limit": {
      "default": 20,
      "description": "Max works to return.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset for pagination.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "author_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

openlibrary_get_subject

Browse works by subject. Returns matching works with edition counts and cover IDs, plus the total work count for the subject. Case and spacing are normalized before lookup, so "Science Fiction" and "science_fiction" are the same request. Subject tags are user-contributed and the vocabulary varies — when a subject returns no works, try a different word form (singular/plural), a synonym, or a broader term.

Parameters3

subject	string	required	Subject name. Normalized before lookup — lowercased with spaces converted to underscores (e.g., "Science Fiction" → "science_fiction") — so varying case or spacing does not change the result.
limit	integer	optional	Max works to return. Subject pages typically show 12 at a time.
offset	integer	optional	Zero-based offset for pagination.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "Subject name. Normalized before lookup — lowercased with spaces converted to underscores (e.g., \"Science Fiction\" → \"science_fiction\") — so varying case or spacing does not change the result."
    },
    "limit": {
      "default": 12,
      "description": "Max works to return. Subject pages typically show 12 at a time.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset for pagination.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "subject"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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). 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 (an ISBN-10 may end in an X check digit), "olid" an edition OLID (OL…M) for target "book" and an author OLID (OL…A) for target "author". Identifiers with path separators or control characters, and author-by-ISBN lookups, are rejected before any request. URLs can be embedded in markdown as ![cover](url).

Parameters4

identifier	string	required	The identifier value, validated against id_type before the URL is built. For "id": a numeric cover or photo ID from work/edition/author data. For "isbn": 10 or 13 digits, hyphens optional — an ISBN-10 may end in an X check digit (e.g., 080442957X). For "olid": an edition OLID (OL…M) for target "book", an author OLID (OL…A) for target "author".
id_type	string	required	"id" is the numeric cover_i / cover ID from search or work results. "isbn" and "olid" look up the cover from those identifiers.
target	string	optional	"book" returns a book cover from covers.openlibrary.org/b/. "author" returns an author photo from covers.openlibrary.org/a/ — use with id_type "id" (photo_id) or "olid" (author OLID).
size	string	optional	Image size. S = small (~45px tall), M = medium (~150px tall), L = large (~400px tall).

Raw schema

{
  "type": "object",
  "properties": {
    "identifier": {
      "type": "string",
      "description": "The identifier value, validated against id_type before the URL is built. For \"id\": a numeric cover or photo ID from work/edition/author data. For \"isbn\": 10 or 13 digits, hyphens optional — an ISBN-10 may end in an X check digit (e.g., 080442957X). For \"olid\": an edition OLID (OL…M) for target \"book\", an author OLID (OL…A) for target \"author\"."
    },
    "id_type": {
      "type": "string",
      "enum": [
        "id",
        "isbn",
        "olid"
      ],
      "description": "\"id\" is the numeric cover_i / cover ID from search or work results. \"isbn\" and \"olid\" look up the cover from those identifiers."
    },
    "target": {
      "default": "book",
      "description": "\"book\" returns a book cover from covers.openlibrary.org/b/. \"author\" returns an author photo from covers.openlibrary.org/a/ — use with id_type \"id\" (photo_id) or \"olid\" (author OLID).",
      "type": "string",
      "enum": [
        "book",
        "author"
      ]
    },
    "size": {
      "default": "M",
      "description": "Image size. S = small (~45px tall), M = medium (~150px tall), L = large (~400px tall).",
      "type": "string",
      "enum": [
        "S",
        "M",
        "L"
      ]
    }
  },
  "required": [
    "identifier",
    "id_type"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md20 KBView on GitHub

@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

Version MCP SDK TypeScript

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

Overview

Open Library's catalog of 20M+ books, editions, authors, and subjects, plus full-text search across Internet Archive's scanned books. Search and browse from any MCP client, drill from a work into its editions or an author into their works, and resolve cover and author-photo URLs. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

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

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.

Capability reference

`openlibrary_search_books` _tool

Free-text query with Solr field prefixes (title:, author:, subject:, publisher:, isbn:, language:) or dedicated filter parameters; 1–100 results per page (default 10), offset pagination
sort: relevance (default), new, old, rating, editions
language accepts a 3-letter MARC code or a translatable 2-letter ISO code; an untranslatable 2-letter code fails as unknown_language_code rather than being silently dropped
include_availability adds live Internet Archive borrow/read status (~200ms latency), off by default; flags Open Library leaves out are omitted rather than reported as false, and availability: null means none was returned for the work
Returns work-level records with edition counts, cover IDs, subjects, and Internet Archive identifiers; content[] text caps Internet Archive IDs and subjects at 5 each per work, structuredContent carries every one

`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, naming openlibrary_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_author or openlibrary_search_books)
A merged work ID stays reachable — the redirect chain is followed to the canonical record, work_id reports the canonical ID, and an enrichment notice names both IDs when they differ
content[] text caps subjects at 10; structuredContent carries the complete list
not_found when 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–100 per page (default 10), offset pagination, with the requested offset echoed in the output
Same work_id validation as openlibrary_get_work — an ISBN resolves to its work through openlibrary_get_edition (id_type: "isbn")
Returns ISBN-10/13, publisher, language, page count, cover IDs, and edition OLIDs (OL…M) per edition
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 still costs one request
not_found when the Work ID doesn't exist or its redirect chain reaches no work

`openlibrary_get_edition` _tool

Resolves 1–50 identifiers per call in a single upstream request — every identifier shares one id_type: isbn (10 or 13 digits, an ISBN-10 may end in an X check digit), oclc (numeric), lccn (unchecked), or olid (OL…M)
Partial success: identifiers that resolve return in editions (request order); the rest land in unresolved with invalid_identifier (malformed, never sent upstream) or not_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 — 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, publisher, language, page count, cover IDs, parent work ID, and an Internet Archive ebook_url when one exists

`openlibrary_search_authors` _tool

Search by name — partial and alternate names match; 1–100 per page (default 10), offset pagination
Returns Author ID (OL…A), alternate names, birth/death dates, top work, work count, top subjects, and average rating
content[] text caps top subjects at 5 per author; structuredContent carries the complete list

`openlibrary_get_author` _tool

Fetch by Author ID (OL…A); 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_found when 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); 1–100 per page (default 20), offset pagination, with the requested offset echoed in the output
Returns title, first-publish date, cover IDs, and Work ID (OL…W) per work
A merged author ID stays reachable — an enrichment notice names the canonical ID when it differs from the one requested
not_found when 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 normalized before lookup (lowercased, spaces → underscores), so case and spacing never change the result; 1–100 per page (default 12), offset pagination, with the requested offset echoed in the output
Returns canonical subject name, normalized subject key, 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
Results key on Internet Archive ia_identifier, not Open Library work IDs — match it against ia_identifiers from openlibrary_search_books to reach the catalogue record
content[] text caps snippets at 3 per item; structuredContent carries every snippet
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 an X check digit), or olid (OL…M for target: "book", OL…A for target: "author"); size is S/M/L (default M)
Identifiers are validated locally before any request — path separators, .., and control characters fail as invalid_identifier, and an author lookup by isbn fails as invalid_target
The Covers API always returns HTTP 200 — a missing cover is a 1×1 placeholder GIF, not an error, which is why local validation exists
Output URL is ready to embed directly as ![cover](url)

`openlibrary://works/{work_id}` _resource

Same fields as openlibrary_get_work, as injectable application/json context for a conversation about a specific book
work_id comes from openlibrary_search_books or openlibrary_get_author_works; a merged ID resolves to the canonical work, whose ID the returned work_id carries, 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 injectable application/json context for a conversation about a specific author
author_id comes from openlibrary_search_authors; a merged ID resolves to the canonical author, whose ID the returned author_id carries, 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:

Complete Open Library REST API coverage — Search, Search Inside (full-text), Books, Authors, Subjects, and Covers APIs, plus Internet Archive availability lookups
Work → editions and author → works drill-down, with explicit OLID cross-links between tool outputs
Configurable User-Agent header (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, and openlibrary_get_editions follow merge redirects and surface the canonical ID via an enrichment notice when a requested ID was merged
Per-item partial failure — openlibrary_get_edition returns resolved editions alongside typed unresolved reasons instead of failing the whole batch
Text-output caps disclosed via enrichment notices (Internet Archive IDs, subjects, snippets) while structuredContent always carries the complete list

Getting started

Public Hosted Instance

A public instance is available at https://openlibrary.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "openlibrary-mcp-server": {
      "type": "streamable-http",
      "url": "https://openlibrary.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

{
  "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):

json

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

json

{
  "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.4.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

Configure environment (optional):

cp .env.example .env
# edit .env to override defaults — no required vars

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`
`OTEL_ENABLED`	Enable OpenTelemetry	`false`

See .env.example for the full list of optional overrides.

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  # Lint, format, typecheck, security
bun run test      # Vitest test suite
bun run lint:mcp  # Validate MCP definitions against spec

Docker

docker build -t openlibrary-mcp-server .
docker run --rm -p 3010:3010 openlibrary-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/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.
`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
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.

Install

Tools (10)

openlibrary_search_booksopenlibrary_search_insideopenlibrary_get_workopenlibrary_get_editionsopenlibrary_get_editionopenlibrary_search_authorsopenlibrary_get_authoropenlibrary_get_author_works

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_PUBLIC_URL

Public origin override for deployments behind a TLS-terminating reverse proxy (e.g. https://mcp.example.com).

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "openlibrary-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/openlibrary-mcp-server@0.3.0",
        "run",
        "start:stdio"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

io.github.cyanheads/openlibrary-mcp-server (MCP Server)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

openlibrary_search_books

openlibrary_search_inside

openlibrary_get_work

openlibrary_get_editions

openlibrary_get_edition

openlibrary_search_authors

openlibrary_get_author

openlibrary_get_author_works

openlibrary_get_subject

openlibrary_get_cover_url

@cyanheads/openlibrary-mcp-server

Overview

Tools

Resources

Capability reference

openlibrary_search_books tool

openlibrary_get_work tool

openlibrary_get_editions tool

openlibrary_get_edition tool

openlibrary_search_authors tool

openlibrary_get_author tool

openlibrary_get_author_works tool

openlibrary_get_subject tool

openlibrary_search_inside tool

openlibrary_get_cover_url tool

openlibrary://works/{work_id} resource

openlibrary://authors/{author_id} resource

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`openlibrary_search_books` _tool

`openlibrary_get_work` _tool

`openlibrary_get_editions` _tool

`openlibrary_get_edition` _tool

`openlibrary_search_authors` _tool

`openlibrary_get_author` _tool

`openlibrary_get_author_works` _tool

`openlibrary_get_subject` _tool

`openlibrary_search_inside` _tool

`openlibrary_get_cover_url` _tool

`openlibrary://works/{work_id}` _resource

`openlibrary://authors/{author_id}` _resource