@cyanheads/gutenberg-mcp-server
Search, browse, and read 78,000+ public-domain books from Project Gutenberg with full plain-text retrieval and offset/limit chunking via MCP. STDIO or Streamable HTTP.
Public Hosted Server: https://gutenberg.caseyjhand.com/mcp
Overview
Project Gutenberg's library of 78,000+ public-domain books. Search by title, author, topic, or language, fetch full book metadata, and read supported UTF-8 plain-text and HTML editions in manageable chunks.
Tools
| Tool | Description |
|---|---|
gutenberg_search_books | Search the catalog by title, author, topic, translator, language, or author lifespan, with pagination and popularity sorting |
gutenberg_get_book | Fetch complete metadata for a book by ID — authors, translators, editors, full formats map, subjects, copyright status |
gutenberg_get_text | Retrieve a book's plain-text content stripped of license boilerplate, with offset/limit chunking or a find jump to a passage |
gutenberg_browse_popular | Browse the most-downloaded books, optionally filtered by language or topic |
The published gutenberg-guide skill covers deciding whether a book can be read, ruling out search blind spots before calling a book missing, finding openings and chapters past front matter, paging long texts, and ranking editions. Plugin installs include it; MCP clients can discover it through the Skills extension and its skill resource.
Capability reference
gutenberg_search_books tool
- Filters:
query(title/author words),topic,translator,languages(catalog codes exactly as results report them, two or three letters:en, noteng),author_year_start/author_year_end,ids,mime_type, andcopyright("true","false","null"; false means public domain in the USA). Live fallback rejects queries over four words and thetranslatorfilter - With both author-year bounds, one author must meet both. The live fallback checks the bounds separately and says so in a notice
sortispopular(default) orascending/descendingby Gutenberg ID. Up to 32 books per page; usetotalCountandhasMoreto page- Each result carries
is_readable(eligible Text formats; mirror file availability is not guaranteed) andhas_plain_text. The local mirror ignores case and accents in query, translator and topic matching; live matching is upstream-defined. Result rows omit translators;gutenberg_get_bookreports them. Fails withtranslator_requires_mirror,query_requires_mirror,page_out_of_range,catalog_rejected, orcatalog_unavailable
gutenberg_get_book tool
- Returns the full
formatsmap (MIME type → download URL) and authors, translators, and editors with birth/death years - Also carries
is_readable,has_plain_text,summary,source_notes, anddownload_count(downloads in the last 30 days, not lifetime) - Reads the local mirror, then the book's own record on the content mirror. Fails with
not_found,catalog_rejected, orcatalog_unavailable
gutenberg_get_text tool
- Reads a book in
offset/limitchunks (defaultlimit20,000, capped at 50,000), with the Gutenberg license header and footer stripped.requestedLimitandappliedLimitreport both - Prefers UTF-8 plain text and falls back to HTML converted to text;
sourceFormatsays which. ReturnstotalChars,length,remainingChars,hasMore, andprovenance(ID, title, license URL). Uselength, notlimit, to compute the nextoffset findjumps to a passage instead of paging to it: the chunk starts at the first match at or afteroffset, andmatchreports itsoffset,length, andlaterMatches. Matching ignores letter case and whitespace runs, and treats straight and curly quotes alike; accents and punctuation must match- Converted HTML editions blank every line that holds no visible character, keep each table row on one line with tab-separated cells, and keep a verse line break as one newline
- Files over 8 MiB are read as four parallel byte ranges when the mirror supports them; a file over 40 MiB fails with
text_too_large - Fails with
not_found,audio_book(media_type "Sound"),no_text_format,offset_out_of_range,passage_not_found,text_file_not_found,text_fetch_rejected,text_too_large,invalid_text_response,text_fetch_failed,catalog_rejected, orcatalog_unavailable
gutenberg_browse_popular tool
- Returns up to 32 titles (
limit, default 20), most downloaded in the last 30 days first.requestedLimitandappliedLimitreport the cap - Optional
languages,topic,mime_type, andcopyrightfilters work as in search.totalInCataloggives the full count - Output reports truncation and carries a
continuationpointing atgutenberg_search_books. Empty results succeed with a notice; fails withcatalog_rejectedorcatalog_unavailable
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.
Gutenberg-specific:
- Searches and lookups read a local SQLite+FTS5 catalog mirror. When the mirror is cold, searches fall back to Gutendex; a book the mirror lacks is read from its per-book RDF record on the content mirror
- Full plain-text retrieval from a Project Gutenberg content mirror, with UTF-8/HTML fallback
- Book text is cached per tenant, so later chunk reads skip the fetch
- No API key required
Agent-friendly output:
is_readableflags Text records with UTF-8 plain text, or HTML without audio formats; a missing mirror file still returnstext_file_not_foundoffset,length,totalChars,remainingChars, andhasMoresupport reliable sequential readsprovenanceandsourceFormaton every text response cover attribution and fidelity
Getting started
Connect to the hosted instance, no install:
claude mcp add --transport http gutenberg-mcp-server https://gutenberg.caseyjhand.com/mcp
Or run it locally:
claude mcp add gutenberg-mcp-server -- npx -y @cyanheads/gutenberg-mcp-server
For other clients, add this to the MCP config file:
{
"mcpServers": {
"gutenberg-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/gutenberg-mcp-server"]
}
}
}
No API key required. For Docker or a source build, see Running the server.
Configuration
| Variable | Description | Default |
|---|---|---|
GUTENDEX_BASE_URL | Gutendex catalog API base URL, used for search and popularity browse when the local catalog mirror cannot answer. | https://gutendex.com/books/ |
GUTENBERG_TEXT_BASE_URL | Content mirror serving the /cache/epub file tree: book text, the bulk catalog archive, and per-book catalog records. | https://gutenberg.pglaf.org |
GUTENBERG_MIRROR_PATH | SQLite catalog path; use a persistent volume in containers. | $XDG_DATA_HOME/gutenberg-mcp-server/gutenberg-catalog.sqlite (~/.local/share when XDG_DATA_HOME is unset, empty, or relative) |
GUTENBERG_MIRROR_REFRESH_CRON | Cron schedule for in-process catalog refresh. | Unset |
MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio |
MCP_SESSION_MODE | HTTP session mode: auto, stateful, or stateless. Overrides the stateless posture the server declares in createApp(). | stateless |
MCP_HTTP_PORT | Port for HTTP server. | 3010 |
MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none |
MCP_LOG_LEVEL | Log level (RFC 5424). | info |
LOGS_DIR | Directory for log files (Node.js only). | <project-root>/logs |
STORAGE_PROVIDER_TYPE | Storage backend. | in-memory |
OTEL_ENABLED | Enable OpenTelemetry instrumentation. | false |
Build the local catalog with npx -y @cyanheads/gutenberg-mcp-server mirror init and check it with mirror verify; mirror refresh re-harvests when the archive has been rebuilt. Each runs under Node or Bun from any directory and prints mirror path: <absolute path> first. From a source checkout, bun run mirror:init, mirror:verify, and mirror:refresh run the built dist/ (build first). The server never harvests on startup, and answers searches from Gutendex and book lookups from each book's RDF record until the first harvest completes. Keep the catalog up to date with mirror refresh on a host scheduler, or set GUTENBERG_MIRROR_REFRESH_CRON.
An existing ./.mirror/gutenberg-catalog.sqlite is read only when GUTENBERG_MIRROR_PATH points at it. A blank or unsubstituted ${…} value for any of these variables reads as unset.
Running the server
Local development
Requires Bun v1.4.4 or higher (or Node.js v24+).
-
Clone and install:
git clone https://github.com/cyanheads/gutenberg-mcp-server.git cd gutenberg-mcp-server && bun install cp .env.example .env # optional overrides -
Build and run:
# One-time build bun run rebuild # Run the built server bun run start:stdio # or bun run start:http -
Run checks and tests:
bun run devcheck # Lint, format, typecheck, security bun run test # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec
Docker
docker run --rm -p 3010:3010 ghcr.io/cyanheads/gutenberg-mcp-server:latest
The image defaults to HTTP transport, stateless session mode, and logs to /var/log/gutenberg-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/gutenberg-mcp-server:latest"]. To build locally, docker build -t gutenberg-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 inits services. |
src/config/server-config.ts | Server-specific environment variable parsing (Gutendex and content-mirror URLs, catalog mirror path and refresh schedule). |
src/mcp-server/tools/definitions/ | Tool definitions (*.tool.ts). |
src/services/gutendex/ | Catalog service — mirror reads, live Gutendex search and browse, per-book RDF lookup. |
src/services/catalog-mirror/ | Local SQLite+FTS5 catalog mirror — RDF ingestion, read helpers, and the mirror CLI. |
src/services/gutenberg-text/ | Full plain-text retrieval, boilerplate stripping, tenant-scoped caching, and chunking. |
skills/gutenberg-guide/ | Published agent skill for reading and discovery workflows, also served over MCP. |
tests/ | Unit and integration tests mirroring src/. |
Development guide
See CLAUDE.md / AGENTS.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no
try/catchin tool logic - Use
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storage - Register new tools via the entry arrays in
src/index.ts - 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
Data attribution
Data from Project Gutenberg is in the public domain. Catalog metadata comes from Project Gutenberg's RDF catalog and, for live searches, Gutendex (MIT license).
License
Apache-2.0 — see LICENSE for details.