openlibrary-mcp-server

Search Books

openlibrary_search_books

Read-only

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.

Input Schema

Name	Required	Description	Default
`isbn`	No	Find works that have editions with this ISBN (10 or 13 digits, hyphens ignored).
`sort`	No	Sort order. "relevance" uses Solr scoring. "new"/"old" sort by first publish year. "rating" by average community rating. "editions" by edition count.	relevance
`limit`	No	Max results to return. Higher values increase response size; prefer 10–20 for exploration.
`query`	No	Full-text search query. Supports Solr field prefixes: title:, author:, subject:, publisher:, isbn:, language:. Omit to use the filter parameters instead.
`title`	No	Filter by title. Matched against work title and alternative titles.
`author`	No	Filter by author name. Partial names work.
`offset`	No	Zero-based offset for pagination.
`subject`	No	Filter by subject tag (e.g., "science fiction", "history").
`language`	No	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.
`publisher`	No	Filter by publisher name. Partial names work (e.g., "Penguin").
`include_availability`	No	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.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`total`	No	Total matching works across all pages.
`works`	No	Matching works, up to limit.
`notice`	No	Guidance when the page is empty or a requested page limit was reduced to 100. Absent when neither applies.
`offset`	No	Zero-based offset of the first returned result.
`queryEcho`	No	The effective search criteria as the server interpreted them — query string plus any active field filters. Absent when only a bare query is used.
`totalCount`	No	Total matching works across all pages — the upstream match count, reported even when this page is empty because offset ran past the end.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedOct 26, 2026

changedInput schema / properties / limit / maximum

Previous value: -100New value: +9007199254740991

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `unknown_language_code`: A 2-letter language value has no MARC equivalent, so no filter could be applied. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_search_query`: Open Library rejects the search query with HTTP 422. `unknown_language_code`: A 2-letter language value has no MARC equivalent, so no filter could be applied. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "unknown_language_code"
-]New value: +[
+  "invalid_search_query",
+  "unknown_language_code"
+]

changedOutput schema / properties / notice / description

Previous value: -"Guidance when the page is empty (how to broaden a query that matched nothing, or which offset to retry when offset ran past the end) or when the text output capped a per-work list. Absent when neither applies."New value: +"Guidance when the page is empty or a requested page limit was reduced to 100. Absent when neither applies."

addedOutput schema / properties / works / items / properties / matching_edition

Added value: +{
+  "additionalProperties": false,
+  "description": "One provider-ranked edition selected by query syntax and field filters, when supplied. Unfielded terms need not all match this edition; this is not every edition record.",
+  "properties": {
+    "edition_id": {
+      "description": "Provider-selected edition OLID (OL…M). Pass to openlibrary_get_edition with id_type \"olid\".",
+      "type": "string"
+    },
+    "languages": {
+      "description": "Selected edition language codes, when supplied.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "publishers": {
+      "description": "Selected edition publisher names, when supplied.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "title": {
+      "description": "Selected edition title, when supplied.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "edition_id"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / works / items / properties / matching_edition_count

Added value: +{
+  "description": "Provider-reported matching-edition count for this search, when supplied. Distinct from the work total edition_count; may be present without a selected edition.",
+  "type": "number"
+}

changedOutput schema / properties / works / items / properties / subjects / description

Previous value: -"Every subject tag the search index returned for this work. The text output caps the rendered list; this array is complete. Absent when no subjects are tagged. For the work record's own curated subject lists (places, times, people), use openlibrary_get_work."New value: +"Every subject tag the search index returned for this work. Absent when no subjects are tagged. For the work record's own curated subject lists (places, times, people), use openlibrary_get_work."

Changed2 schema fields changedSep 24, 2026

changedOutput schema / properties / works / items / properties / availability / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "available_to_borrow": {
-        "description": "True when the book can be borrowed.",
-        "type": "boolean"
-      },
-      "available_to_browse": {
-        "description": "True when the book can be browsed for free.",
-        "type": "boolean"
-      },
-      "available_to_waitlist": {
-        "description": "True when a waitlist is available.",
-        "type": "boolean"
-      },
-      "is_lendable": {
-        "description": "True when the book can be lent.",
-        "type": "boolean"
-      },
-      "is_previewable": {
-        "description": "True when a limited preview is available.",
-        "type": "boolean"
-      },
-      "is_readable": {
-        "description": "True when the book is freely readable online.",
-        "type": "boolean"
-      },
-      "is_restricted": {
-        "description": "True when access is restricted.",
-        "type": "boolean"
-      },
-      "openlibrary_edition": {
-        "description": "Edition OLID the availability check was resolved against.",
-        "type": "string"
-      },
-      "status": {
-        "description": "Availability status string from Internet Archive.",
-        "type": "string"
-      }
-    },
-    "required": [
-      "status",
-      "available_to_browse",
-      "available_to_borrow",
-      "available_to_waitlist",
-      "is_readable",
-      "is_lendable",
-      "is_previewable",
-      "is_restricted"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "available_to_borrow": {
+        "description": "True when the book can be borrowed. Absent when not reported.",
+        "type": "boolean"
+      },
+      "available_to_browse": {
+        "description": "True when the book can be browsed for free. Absent when not reported.",
+        "type": "boolean"
+      },
+      "available_to_waitlist": {
+        "description": "True when a waitlist is available. Absent when not reported.",
+        "type": "boolean"
+      },
+      "is_lendable": {
+        "description": "True when the book can be lent. Absent when not reported.",
+        "type": "boolean"
+      },
+      "is_previewable": {
+        "description": "True when a limited preview is available. Absent when not reported.",
+        "type": "boolean"
+      },
+      "is_readable": {
+        "description": "True when the book is freely readable online. Absent when not reported.",
+        "type": "boolean"
+      },
+      "is_restricted": {
+        "description": "True when access is restricted. Absent when not reported.",
+        "type": "boolean"
+      },
+      "openlibrary_edition": {
+        "description": "Edition OLID the availability check was resolved against. Absent when not reported.",
+        "type": "string"
+      },
+      "status": {
+        "description": "Availability status from Internet Archive, e.g. \"open\" (freely readable), \"borrow_available\", \"borrow_unavailable\", \"private\", or \"error\" (the lending lookup failed, so no flags accompany it). \"unknown\" when Open Library sent no status.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "status"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / works / items / properties / availability / description

Previous value: -"Live reading availability from Internet Archive. Present when include_availability is true and the work has an Internet Archive item. Null when include_availability is true but no IA item exists."New value: +"Live reading availability from Internet Archive, present when include_availability is true. Open Library leaves flags out for some works — an absent flag is unknown, not false. Null means no availability was returned for the work: always so without an Internet Archive item, and sometimes so for a work that has one."

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "total",
+      "offset",
+      "works"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `unknown_language_code`: A 2-letter language value has no MARC equivalent, so no filter could be applied. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "unknown_language_code"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "total",
-  "offset",
-  "works"
-]

Changed3 schema fields changedJul 26, 2026

changedOutput schema / properties / notice / description

Previous value: -"Recovery guidance when results are empty — echoes the search criteria and suggests how to broaden. Absent when results are found."New value: +"Guidance when the page is empty (how to broaden a query that matched nothing, or which offset to retry when offset ran past the end) or when the text output capped a per-work list. Absent when neither applies."

changedOutput schema / properties / totalCount / description

Previous value: -"Total matching works across all pages. Absent when results are empty."New value: +"Total matching works across all pages — the upstream match count, reported even when this page is empty because offset ran past the end."

changedOutput schema / properties / works / items / properties / subjects / description

Previous value: -"Up to 5 subject tags. Absent when no subjects are tagged."New value: +"Every subject tag the search index returned for this work. The text output caps the rendered list; this array is complete. Absent when no subjects are tagged. For the work record's own curated subject lists (places, times, people), use openlibrary_get_work."

Changed4 schema fields changedJul 25, 2026

changedInput schema / properties / language / description

Previous value: -"Two-letter ISO 639-1 language code (e.g., \"en\", \"fr\"). Influences but does not exclude results; use language:fr in query to hard-filter."New value: +"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."

addedInput schema / properties / language / pattern
```
Added value: +"^[A-Za-z]{2,3}$"
```

changedOutput schema / properties / works / items / properties / ebook_access / description

Previous value: -"\"public\" = freely readable. \"borrowable\" = borrow on Internet Archive. \"printdisabled\" = access for print-disabled users. \"no_ebook\" = no digital version."New value: +"\"public\" = freely readable. \"borrowable\" = borrow on Internet Archive. \"printdisabled\" = access for print-disabled users. \"no_ebook\" = no digital version. \"unclassified\" = a digital copy may exist but its access tier is not recorded."

changedOutput schema / properties / works / items / properties / ebook_access / enum

Previous value: -[
-  "no_ebook",
-  "printdisabled",
-  "borrowable",
-  "public"
-]New value: +[
+  "no_ebook",
+  "unclassified",
+  "printdisabled",
+  "borrowable",
+  "public"
+]

Changed1 schema field changedJun 13, 2026

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total matching works across all pages. Absent when results are empty.",
+  "type": "number"
+}

Changed3 schema fields changedMay 30, 2026

removedOutput schema / properties / message

Removed value: -{
-  "description": "Recovery hint when results are empty — echoes the search criteria and suggests how to broaden. Absent when results are found.",
-  "type": "string"
-}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Recovery guidance when results are empty — echoes the search criteria and suggests how to broaden. Absent when results are found.",
+  "type": "string"
+}

addedOutput schema / properties / queryEcho

Added value: +{
+  "description": "The effective search criteria as the server interpreted them — query string plus any active field filters. Absent when only a bare query is used.",
+  "type": "string"
+}

First observedMay 25, 2026

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: results are work-level (not edition-level) and include edition counts, cover IDs, and reading availability, which prevents an agent from misreading the result shape. It omits any mention of pagination limits or the ~200ms availability cost (that only lives in the schema), so it is not fully self-sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tightly packed sentences with no waste: purpose and scope first, then invocation modes, then result granularity and the drill-down sibling. Everything an agent needs is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 11 parameters, full schema coverage, and an output schema, the description does enough: it establishes work-level granularity, query-vs-filter usage, and the next step. The remaining gap is that it never positions itself against openlibrary_search_inside, leaving a real ambiguity for an agent deciding between metadata search and full-text-in-book search.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter in detail — including Solr field prefixes, sort enum meanings, and the MARC language code rules — and the description largely restates that list ("title, author, subject, publisher, ISBN, language"). It adds the useful query-vs-filters dichotomy but no syntax or format detail the schema lacks, so baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Full-text book search across Open Library works") and immediately scopes the result granularity to work-level records. It is clearly differentiated from siblings search_authors and search_inside by naming the books/works domain and by explicitly pointing to openlibrary_get_editions for drill-down.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete invocation guidance: "Use query for general search or combine specific field filters," plus the follow-up routing to openlibrary_get_editions once a work is found. It stops short of saying when NOT to use this tool — notably it never contrasts with openlibrary_search_inside, the sibling that searches inside book text, which is the most likely confusion point.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All openlibrary-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.