@cyanheads/gutenberg-mcp-server

中文文档
0.3.3发布于 2026/11/12Apache-2.0TypeScriptES Module近 30 天下载 1973

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.

原始使用文档
文档目录18 节
  1. Overview
  2. Tools
  3. Capability reference
  4. gutenberg_search_books tool
  5. gutenberg_get_book tool
  6. gutenberg_get_text tool
  7. gutenberg_browse_popular tool
  8. Features
  9. Getting started
  10. Configuration
  11. Running the server
  12. Local development
  13. Docker
  14. Project structure
  15. Development guide
  16. Contributing
  17. Data attribution
  18. License

@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.

4 Tools

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework

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

ToolDescription
gutenberg_search_booksSearch the catalog by title, author, topic, translator, language, or author lifespan, with pagination and popularity sorting
gutenberg_get_bookFetch complete metadata for a book by ID — authors, translators, editors, full formats map, subjects, copyright status
gutenberg_get_textRetrieve a book's plain-text content stripped of license boilerplate, with offset/limit chunking or a find jump to a passage
gutenberg_browse_popularBrowse 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, not eng), author_year_start/author_year_end, ids, mime_type, and copyright ("true", "false", "null"; false means public domain in the USA). Live fallback rejects queries over four words and the translator filter
  • With both author-year bounds, one author must meet both. The live fallback checks the bounds separately and says so in a notice
  • sort is popular (default) or ascending/descending by Gutenberg ID. Up to 32 books per page; use totalCount and hasMore to page
  • Each result carries is_readable (eligible Text formats; mirror file availability is not guaranteed) and has_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_book reports them. Fails with translator_requires_mirror, query_requires_mirror, page_out_of_range, catalog_rejected, or catalog_unavailable

gutenberg_get_book tool

  • Returns the full formats map (MIME type → download URL) and authors, translators, and editors with birth/death years
  • Also carries is_readable, has_plain_text, summary, source_notes, and download_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, or catalog_unavailable

gutenberg_get_text tool

  • Reads a book in offset/limit chunks (default limit 20,000, capped at 50,000), with the Gutenberg license header and footer stripped. requestedLimit and appliedLimit report both
  • Prefers UTF-8 plain text and falls back to HTML converted to text; sourceFormat says which. Returns totalChars, length, remainingChars, hasMore, and provenance (ID, title, license URL). Use length, not limit, to compute the next offset
  • find jumps to a passage instead of paging to it: the chunk starts at the first match at or after offset, and match reports its offset, length, and laterMatches. 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, or catalog_unavailable

gutenberg_browse_popular tool

  • Returns up to 32 titles (limit, default 20), most downloaded in the last 30 days first. requestedLimit and appliedLimit report the cap
  • Optional languages, topic, mime_type, and copyright filters work as in search. totalInCatalog gives the full count
  • Output reports truncation and carries a continuation pointing at gutenberg_search_books. Empty results succeed with a notice; fails with catalog_rejected or catalog_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_readable flags Text records with UTF-8 plain text, or HTML without audio formats; a missing mirror file still returns text_file_not_found
  • offset, length, totalChars, remainingChars, and hasMore support reliable sequential reads
  • provenance and sourceFormat on 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

VariableDescriptionDefault
GUTENDEX_BASE_URLGutendex catalog API base URL, used for search and popularity browse when the local catalog mirror cannot answer.https://gutendex.com/books/
GUTENBERG_TEXT_BASE_URLContent mirror serving the /cache/epub file tree: book text, the bulk catalog archive, and per-book catalog records.https://gutenberg.pglaf.org
GUTENBERG_MIRROR_PATHSQLite 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_CRONCron schedule for in-process catalog refresh.Unset
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_SESSION_MODEHTTP session mode: auto, stateful, or stateless. Overrides the stateless posture the server declares in createApp().stateless
MCP_HTTP_PORTPort for HTTP server.3010
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (RFC 5424).info
LOGS_DIRDirectory for log files (Node.js only).<project-root>/logs
STORAGE_PROVIDER_TYPEStorage backend.in-memory
OTEL_ENABLEDEnable 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

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools and inits services.
src/config/server-config.tsServer-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/catch in tool logic
  • Use ctx.log for request-scoped logging, ctx.state for 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.

版本与发布记录

@cyanheads/gutenberg-mcp-server 共发布 16 个版本,首次发布于 2026/06/01;过去 12 个月发布了 16 个版本。

版本发布日期距今
0.3.3latest2026/11/124 天前
0.3.22026/11/0114 天前
0.3.12026/10/3115 天前
0.3.02026/10/2917 天前
0.2.02026/10/1829 天前
0.1.112026/10/1730 天前

关于 @cyanheads/gutenberg-mcp-server 的常见问题

@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.

如何安装 @cyanheads/gutenberg-mcp-server?

在项目目录运行 npm install @cyanheads/gutenberg-mcp-server,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gutenberg-mcp-server,可以用 npx gutenberg-mcp-server 直接运行。

@cyanheads/gutenberg-mcp-server 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@cyanheads/gutenberg-mcp-server 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@cyanheads/gutenberg-mcp-server 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@cyanheads/gutenberg-mcp-server 可以商用吗?

@cyanheads/gutenberg-mcp-server 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@cyanheads/gutenberg-mcp-server 的下载量有多少?

根据 npm 官方下载统计,@cyanheads/gutenberg-mcp-server 在 2026/10/11 – 2026/11/09 这 30 天内被下载 1,973 次,日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@cyanheads/gutenberg-mcp-server 还在维护吗?

最新版本 0.3.3 发布于 2026/11/12(4 天前);至今共发布 16 个版本,其中过去 12 个月发布了 16 个;首次发布于 2026/06/01。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。