gutenberg-mcp-server

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.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Words to match against book titles and author names (case-insensitive, space-separated). Example: \"dickens expectations\" matches Great Expectations by Charles Dickens.",
      "type": "string"
    },
    "topic": {
      "description": "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.",
      "type": "string"
    },
    "languages": {
      "description": "Filter to books in any of these two-character ISO 639-1 language codes. Example: [\"en\"] for English, [\"fr\", \"de\"] for French or German.",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 2
      }
    },
    "author_year_start": {
      "description": "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.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "author_year_end": {
      "description": "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.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "sort": {
      "default": "popular",
      "description": "Result ordering. \"popular\" (default) sorts by download count descending. \"ascending\" and \"descending\" sort by Gutenberg ID number.",
      "type": "string",
      "enum": [
        "popular",
        "ascending",
        "descending"
      ]
    },
    "ids": {
      "description": "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.",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "page": {
      "default": 1,
      "description": "Page number for paginated results (1-indexed). Each page returns up to 32 books. Use totalCount to determine total pages.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "books": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Gutenberg ID — pass to gutenberg_get_book for the full record or gutenberg_get_text to read the book."
          },
          "title": {
            "type": "string",
            "description": "Book title."
          },
          "authors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Author name in \"Last, First\" format."
                },
                "birth_year": {
                  "description": "Author birth year, or null if unknown.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "death_year": {
                  "description": "Author death year, or null if unknown or still living.",
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "name",
                "birth_year",
                "death_year"
              ],
              "additionalProperties": false,
              "description": "Author entry."
            },
            "description": "Author(s) of the work."
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Two-character language codes for this edition."
          },
          "subjects": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Library of Congress subject headings."
          },
          "download_count": {
            "type": "number",
            "description": "Total downloads from Project Gutenberg — a real popularity signal reflecting actual reader interest."
          },
          "has_plain_text": {
            "type": "boolean",
            "description": "True if the book has media_type \"Text\" AND a UTF-8 text/plain format available — prerequisite for gutenberg_get_text."
          }
        },
        "required": [
          "id",
          "title",
          "authors",
          "languages",
          "subjects",
          "download_count",
          "has_plain_text"
        ],
        "additionalProperties": false,
        "description": "Book entry."
      },
      "description": "Matching books, ordered by the sort parameter."
    },
    "totalCount": {
      "type": "number",
      "description": "Total number of books matching the query across all pages."
    },
    "page": {
      "type": "number",
      "description": "Current page number."
    },
    "hasMore": {
      "type": "boolean",
      "description": "True if there are additional pages of results."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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. `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.",
              "examples": [
                "no_results",
                "page_out_of_range",
                "catalog_unavailable"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "books",
        "totalCount",
        "page",
        "hasMore"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch complete metadata for a Project Gutenberg book by ID — title, authors (with birth/death years), translators, editors, subjects, bookshelves, languages, copyright status, and the full formats map with download URLs for each available format (plain text, HTML, EPUB, cover image, etc.). Use this before gutenberg_get_text to confirm a plain-text format is available and to get the direct download URL.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Project Gutenberg book ID. Visible in Gutenberg URLs (e.g., gutenberg.org/ebooks/1342) and returned by gutenberg_search_books and gutenberg_browse_popular. Example: 1342 for Pride and Prejudice, 2600 for War and Peace."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Gutenberg ID."
    },
    "title": {
      "type": "string",
      "description": "Book title."
    },
    "authors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Author name in \"Last, First\" format."
          },
          "birth_year": {
            "description": "Birth year, or null if unknown.",
            "type": [
              "number",
              "null"
            ]
          },
          "death_year": {
            "description": "Death year, or null if unknown or still living.",
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "birth_year",
          "death_year"
        ],
        "additionalProperties": false,
        "description": "Author entry."
      },
      "description": "Primary author(s)."
    },
    "translators": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Translator name."
          },
          "birth_year": {
            "description": "Birth year, or null if unknown.",
            "type": [
              "number",
              "null"
            ]
          },
          "death_year": {
            "description": "Death year, or null if unknown.",
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "birth_year",
          "death_year"
        ],
        "additionalProperties": false,
        "description": "Translator entry."
      },
      "description": "Translators, if this is a translated work."
    },
    "editors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Editor name."
          },
          "birth_year": {
            "description": "Birth year, or null if unknown.",
            "type": [
              "number",
              "null"
            ]
          },
          "death_year": {
            "description": "Death year, or null if unknown.",
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "birth_year",
          "death_year"
        ],
        "additionalProperties": false,
        "description": "Editor entry."
      },
      "description": "Editors, if any."
    },
    "subjects": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Library of Congress subject headings."
    },
    "bookshelves": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Project Gutenberg bookshelf categories (e.g., \"Best Books Ever Listings\", \"Category: Classics of Literature\")."
    },
    "languages": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Two-character language codes for this edition."
    },
    "copyright": {
      "description": "Copyright status: false = public domain in the USA, true = under copyright, null = unknown.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "media_type": {
      "type": "string",
      "description": "\"Text\" for readable books, \"Sound\" for audio books. Only \"Text\" books have plain-text content available for gutenberg_get_text."
    },
    "download_count": {
      "type": "number",
      "description": "Total downloads — popularity signal."
    },
    "summary": {
      "description": "First entry of summaries — the primary auto-generated summary of the work, or null when Gutendex has none.",
      "type": [
        "string",
        "null"
      ]
    },
    "summaries": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Every summary Gutendex holds for this work, in upstream order. Usually one; some records carry a long and a short variant. Empty when there are none."
    },
    "formats": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Map of MIME type to download URL. Key types: \"text/plain; charset=utf-8\" (preferred for gutenberg_get_text), \"text/html\", \"application/epub+zip\", \"image/jpeg\" (cover). Not every format is present for every book."
    },
    "has_plain_text": {
      "type": "boolean",
      "description": "True if media_type is \"Text\" AND a UTF-8 text/plain format (\"text/plain; charset=utf-8\") is present in formats — prerequisite for gutenberg_get_text."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: No book exists with the given ID. `catalog_unavailable`: The Project Gutenberg catalog did not answer within the time this server allows for one lookup. Other values are possible when a failure originates below the handler.",
              "examples": [
                "not_found",
                "catalog_unavailable"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "id",
        "title",
        "authors",
        "translators",
        "editors",
        "subjects",
        "bookshelves",
        "languages",
        "copyright",
        "media_type",
        "download_count",
        "summary",
        "summaries",
        "formats",
        "has_plain_text"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Retrieve the plain-text content of a Project Gutenberg book, stripped of the standard license header and footer so the response contains only the literary work. For long works — novels routinely run 500KB–2MB — use offset and limit to read in chunks rather than fetching the whole book at once. The response reports totalChars and remainingChars for reliable pagination. Prefers UTF-8 plain text; falls back to an HTML edition converted to text; refuses audio books (media_type "Sound") with a clear error.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Project Gutenberg book ID. Use gutenberg_search_books or gutenberg_get_book to find IDs. Example: 1342 for Pride and Prejudice, 2600 for War and Peace, 84 for Frankenstein."
    },
    "offset": {
      "default": 0,
      "description": "Character offset into the stripped literary text at which to start reading. 0 returns the beginning of the work. To read subsequent chunks, use offset = prior_offset + prior_length (the length field from the previous response — NOT offset + limit, because the actual returned length may be slightly less than limit due to paragraph-boundary trimming).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "default": 20000,
      "description": "Maximum number of characters to return in this chunk. Default 20,000 (~4–5 pages of prose). Increase toward 50,000 for large context windows. The actual returned length may be slightly less than limit when a natural paragraph boundary is found within 500 characters of the limit — check the length field in the response for the actual character count returned.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50000
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Gutenberg book ID."
    },
    "title": {
      "type": "string",
      "description": "Book title, from the catalog record."
    },
    "text": {
      "type": "string",
      "description": "The requested chunk of literary text, stripped of Gutenberg license boilerplate. Encoding: UTF-8. Line endings: normalized to LF."
    },
    "offset": {
      "type": "number",
      "description": "Character offset where this chunk begins."
    },
    "length": {
      "type": "number",
      "description": "Number of characters in this chunk."
    },
    "totalChars": {
      "type": "number",
      "description": "Total characters in the stripped literary text. Use with offset and length to determine progress and plan subsequent calls."
    },
    "remainingChars": {
      "type": "number",
      "description": "Characters remaining after this chunk (totalChars - offset - length). 0 means this chunk includes the end of the book."
    },
    "hasMore": {
      "type": "boolean",
      "description": "True if there is more text after this chunk. When true, call again with offset = offset + length."
    },
    "provenance": {
      "type": "string",
      "description": "One-line source note with Project Gutenberg ID, title, and license URL."
    },
    "sourceFormat": {
      "type": "string",
      "enum": [
        "text/plain; charset=utf-8",
        "text/plain; charset=us-ascii",
        "text/html"
      ],
      "description": "The format that was fetched. \"text/html\" indicates HTML-to-text conversion was applied because no plain-text format was available."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: No book exists with the given ID. `audio_book`: The book is an audio recording (media_type \"Sound\"), not a text book — no literary plain text is available. `no_text_format`: The book has no UTF-8 plain-text or HTML edition available to read (for example an older ASCII-only entry). `offset_out_of_range`: The offset is greater than or equal to totalChars (past the end of the book). `text_fetch_failed`: The Gutenberg file server returned an error or did not respond within the timeout. `catalog_unavailable`: The catalog lookup that precedes reading a book did not answer within the time this server allows. Other values are possible when a failure originates below the handler.",
              "examples": [
                "not_found",
                "audio_book",
                "no_text_format",
                "offset_out_of_range",
                "text_fetch_failed",
                "catalog_unavailable"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "id",
        "title",
        "text",
        "offset",
        "length",
        "totalChars",
        "remainingChars",
        "hasMore",
        "provenance",
        "sourceFormat"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Browse the most-downloaded Project Gutenberg books, ordered by popularity. Returns up to 32 titles with their Gutenberg IDs, authors, languages, and download counts. Optionally filter by language or topic. Use this as a discovery entry point — "what are the most popular classics in French?" — or as a heartbeat check that the catalog is reachable.

{
  "type": "object",
  "properties": {
    "languages": {
      "description": "Restrict to books in these languages (two-character ISO 639-1 codes). Example: [\"en\"] for English only, [\"de\", \"fr\"] for German or French. Omit for all languages.",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 2
      }
    },
    "topic": {
      "description": "Filter by a subject or bookshelf keyword (case-insensitive phrase match). Example: \"science fiction\", \"adventure\", \"detective\". Applies on top of the language filter.",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "description": "Number of books to return (1–32). Default 20 gives a useful overview without overwhelming context.",
      "type": "integer",
      "minimum": 1,
      "maximum": 32
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "books": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Gutenberg ID."
          },
          "title": {
            "type": "string",
            "description": "Book title."
          },
          "authors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Author name in \"Last, First\" format."
                },
                "birth_year": {
                  "description": "Birth year, or null if unknown.",
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "death_year": {
                  "description": "Death year, or null if unknown or still living.",
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "name",
                "birth_year",
                "death_year"
              ],
              "additionalProperties": false,
              "description": "Author entry."
            },
            "description": "Author(s)."
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Language codes."
          },
          "download_count": {
            "type": "number",
            "description": "Total downloads — the basis for the popularity ranking."
          },
          "has_plain_text": {
            "type": "boolean",
            "description": "True if media_type is \"Text\" AND a UTF-8 text/plain format is available via gutenberg_get_text."
          }
        },
        "required": [
          "id",
          "title",
          "authors",
          "languages",
          "download_count",
          "has_plain_text"
        ],
        "additionalProperties": false,
        "description": "Book entry."
      },
      "description": "Top books by download count, most popular first."
    },
    "totalInCatalog": {
      "type": "number",
      "description": "Total books matching the filter in the full catalog (useful for context — \"top 20 of 60,000\")."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when the catalog held more matches than were returned."
    },
    "shown": {
      "type": "number",
      "description": "Number of books returned in this response."
    },
    "cap": {
      "type": "number",
      "description": "The limit that was applied."
    },
    "truncationCeiling": {
      "description": "Download count of the least-popular book shown — omitted books have at most this many downloads.",
      "type": "number"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `no_results`: No books match the language/topic filter combination. `catalog_unavailable`: The Project Gutenberg catalog did not answer within the time this server allows for one browse. Other values are possible when a failure originates below the handler.",
              "examples": [
                "no_results",
                "catalog_unavailable"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "books",
        "totalInCatalog",
        "truncated",
        "shown",
        "cap"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}