gutenberg-mcp-server

Search Gutenberg Books

gutenberg_search_books

Read-onlyIdempotent

Search the Project Gutenberg catalog of 78,000+ public-domain books. Matches title and author name with query words; filters by topic (subject or bookshelf keyword), language, author lifespan, or a specific list of Gutenberg IDs. Results are ordered by popularity (download count) by default. Returns book ID, title, authors, languages, subjects, and download count — use gutenberg_get_book for the full formats map before fetching text.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ids`	No	Narrow results to specific Gutenberg ID numbers. Other filters still apply. Useful for batch pre-fetching known IDs; use gutenberg_get_book for single-ID lookups.
`page`	No	Page number for paginated results (1-indexed). Each page returns up to 32 books. Use totalCount to determine total pages.
`sort`	No	Result ordering. "popular" (default) sorts by download count descending. "ascending" and "descending" sort by Gutenberg ID number.	popular
`query`	No	Words to match against book titles and author names (case-insensitive, space-separated). Example: "dickens expectations" matches Great Expectations by Charles Dickens.
`topic`	No	Case-insensitive phrase to match against subjects and bookshelves. Example: "detective" returns books on the "Detective and Mystery Stories" bookshelf. Separate from query — topic searches categorization metadata, not title/author.
`languages`	No	Filter to books in any of these two-character ISO 639-1 language codes. Example: ["en"] for English, ["fr", "de"] for French or German.
`author_year_end`	No	Include only books with at least one author alive on or before this year. Example: author_year_start=1800 with author_year_end=1899 returns books with 19th-century authors.
`author_year_start`	No	Include only books with at least one author alive on or after this year (positive = CE, negative = BCE). Combine with author_year_end for a range.

Output Schema

TableJSON Schema

Name	Required	Description
`page`	No	Current page number.
`books`	No	Matching books, ordered by the sort parameter.
`error`	No	Present when the call failed. Absent on success.
`hasMore`	No	True if there are additional pages of results.
`totalCount`	No	Total number of books matching the query across all pages.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 20, 2026
- removedOutput schema / properties / books / items / properties / authors / items / properties / birth_year / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / books / items / properties / authors / items / properties / birth_year / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / books / items / properties / authors / items / properties / death_year / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / books / items / properties / authors / items / properties / death_year / type
```
Added value: +[
+  "number",
+  "null"
+]
```

Changed2 schema fields changedAug 23, 2026

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_results`: The query matched no books in the catalog. `page_out_of_range`: The requested page number is past the last page of results for this query. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_results`: The query matched no books in the catalog. `page_out_of_range`: The requested page number is past the last page of results for this query. `catalog_unavailable`: The Project Gutenberg catalog did not answer within the time this server allows for one search. Other values are possible when a failure originates below the handler."

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

Previous value: -[
-  "no_results",
-  "page_out_of_range"
-]New value: +[
+  "no_results",
+  "page_out_of_range",
+  "catalog_unavailable"
+]

Changed6 schema fields changedAug 22, 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": [
+      "books",
+      "totalCount",
+      "page",
+      "hasMore"
+    ]
+  },
+  {
+    "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: `no_results`: The query matched no books in the catalog. `page_out_of_range`: The requested page number is past the last page of results for this query. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_results",
+            "page_out_of_range"
+          ],
+          "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: -[
-  "books",
-  "totalCount",
-  "page",
-  "hasMore"
-]

Changed1 schema field changedJul 11, 2026

changedOutput schema / properties / books / items / properties / has_plain_text / description

Previous value: -"True if the book has media_type \"Text\" AND a text/plain format available — prerequisite for gutenberg_get_text."New value: +"True if the book has media_type \"Text\" AND a UTF-8 text/plain format available — prerequisite for gutenberg_get_text."

First observedJun 16, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, lowering the bar. The description adds meaningful behavior beyond those: result ordering by popularity, the matching semantics over title/author, and the library scope (78,000+ public-domain books). It does not discuss pagination, but the schema's page parameter handles that.

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?

Two sentences, no filler, and the main search capability is front-loaded. Every clause adds useful information: scope, matching behavior, filters, ordering, return fields, and the pointer to gutenberg_get_book.

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

Completeness5/5

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

Given the 8 optional parameters, 100% schema coverage, read-only annotations, and an output schema, the description needs only to convey routing and high-level behavior. It does so completely, including the important downstream instruction to use gutenberg_get_book before fetching text.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by grouping parameters into meaningful categories (topic, language, author lifespan, IDs) and clarifying the separation between query and topic. It also highlights the default sort behavior, which aids correct tool invocation.

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: search the Project Gutenberg catalog, with explicit matching criteria (title/author, topic, language, author lifespan, IDs) and output fields. It distinguishes itself by naming gutenberg_get_book for the next step, and the broad search scope separates it from sibling browse/get tools.

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?

Clearly frames when to use this tool: when searching the catalog with filters. It explicitly routes the agent to gutenberg_get_book for the full formats map before fetching text, and the ids parameter schema reinforces that single-ID lookups should use gutenberg_get_book. It does not explicitly contrast with gutenberg_browse_popular, though the intent is reasonably inferable.

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

All gutenberg-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.