@cyanheads/gutenberg-mcp-server

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

搜索、浏览和阅读Gutenberg项目78,000+公共域名书籍,通过MCP进行全文检索并抵消/限制块。 (原始内容存档于2012-10-12). STIO or Streamable HTTP.

中文使用文档
文档目录18 节
  1. 概览
  2. 工具
  3. 能力参考
  4. gutenberg_search_books 工具
  5. gutenberg_get_book 工具
  6. gutenberg_get_text 工具
  7. gutenberg_browse_popular 工具
  8. 特征
  9. 开始
  10. 配置
  11. 运行服务器
  12. 地方发展
  13. 夹克
  14. 项目结构
  15. 发展指南
  16. 捐款
  17. 数据属性
  18. 许可证

@cyanheads/gutenberg-mcp-服务器

搜索、浏览和阅读Gutenberg项目78,000+公共域名书籍,通过MCP进行全文检索并抵消/限制块。 (原始内容存档于2012-10-12). STIO or Streamable HTTP.

4 个工具

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework


概览

古腾堡项目图书馆藏书7.8万多册. 按标题、作者、主题或语言搜索,获取完整的书本元数据,并读取支持的 UTF-8 纯文本和 HTML 版本的可管理块.

工具

工具说明
gutenberg_search_books按标题、作者、话题、翻译、语言或作者寿命搜索目录,并进行页标和受欢迎度排序
gutenberg_get_book由 ID 获取一本书的完整元数据——作者、翻译、编辑、完整格式地图、主题、版权状况
gutenberg_get_text取出一本书的纯文本内容,取出牌照锅炉板,并有抵消/限制块或一个 find 跳转到一段
gutenberg_browse_popular浏览最下行的书,可选择按语言或主题过滤

发表 gunenberg 向导 技能包括决定是否可读出一本书,在将一本书调出之前排除搜索盲点,寻找打开处和章节过去前题,呼出长文本,以及排名版本。 插件安装包括它;MCP客户端可以通过技能扩展及其技能资源来发现它.


能力参考

gutenberg_search_books 工具

  • 过滤器 : query (标题/作者词), topic, (中文(简体) ), translator, (中文(简体) ), languages (目录编码恰好是结果报告,两到三个字母: en没有 eng, (中文(简体) ), author_year_start编号 :author_year_end, (中文(简体) ), ids, (中文(简体) ), mime_type,以及 copyright (单位:千美元)"true", (中文(简体) ), "false", (中文(简体) ), "null";假指在美国的公有领域. 直播倒计时 拒绝超过四个字的询问 translator 过滤器
  • 在两个作者年限内,一位作者必须同时与两位作者会面。 现场倒计时检查界限 并在通知中说
  • sort 实值 popular (违约)或 ascending编号 :descending 由古腾堡身份证。 每页最多32本;使用 totalCount 财务报告和审定财务报表 hasMore 到页面
  • 每个结果都包含 is_readable (合格文本格式;无法保证镜像文件可用性)和 has_plain_text。本地镜像在查询、翻译和专题匹配中忽略了大小写和口音;现场匹配是上游定义的。 结果行省略了翻译; gutenberg_get_book 报告他们。 失败者 translator_requires_mirror, (中文(简体) ), query_requires_mirror, (中文(简体) ), page_out_of_range, (中文(简体) ), catalog_rejected,或 catalog_unavailable

gutenberg_get_book 工具

  • 返回全部内容 formats 地图(MIME类型-下载 URL)和作者、翻译和有出生/死亡年数的编辑
  • 还带着 is_readable, (中文(简体) ), has_plain_text, (中文(简体) ), summary, (中文(简体) ), source_notes,以及 download_count (过去30天的负载,而不是一生)
  • 读取当地镜像,后由本作在内容镜上自行收录. 失败者 not_found, (中文(简体) ), catalog_rejected,或 catalog_unavailable

gutenberg_get_text 工具

  • 读取一本书 offset编号 :limit 块( 默认) limit 2万元,封顶为5万元),古腾堡牌照头和脚被剥去. requestedLimit 财务报告和审定财务报表 appliedLimit 两个报告
  • 优先使用 UTF-8 纯文本并返回 HTML 转换为文本; sourceFormat 说哪一个。 回返 totalChars, (中文(简体) ), length, (中文(简体) ), remainingChars, (中文(简体) ), hasMore,以及 provenance (ID,标题,许可证 URL). 使用 length没有 limit,用于计算下一个 offset
  • find 跳转到一段而不是呼它:块从第一次比赛开始,时间或之后 offset,以及 match 报告 offset, (中文(简体) ), length,以及 laterMatches。匹配忽略了字母大小写和白空间运行,对直线和卷曲的引文一视同仁;口音和平分必须匹配
  • 转换的 HTML 版本空白了没有可见字符的每行, 将每个表格行保留在有分页单元格的一行上, 并将一行换行保留为一行
  • 当镜像支持时, 8 MiB 以上的文件会被读取为 4 个平行字节区域; 40 个以上的 MiB 文件失败 text_too_large
  • 失败者 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,或 catalog_unavailable

gutenberg_browse_popular 工具

  • 最多32个头衔limit,默认为 20),大多数下载时间为前30天. requestedLimit 财务报告和审定财务报表 appliedLimit 报告上限
  • 可选 languages, (中文(简体) ), topic, (中文(简体) ), mime_type,以及 copyright 过滤器在搜索中有效 . totalInCatalog 给出全部数
  • 产出报告截断并带有 continuation 指点 gutenberg_search_books。空结果在通知中成功;失败 catalog_rejected 或者说 catalog_unavailable

特征

建造在 @cyanheads/mcp-ts-core: stdio和可流式的 HTTP 传输器,可插接式(none 编号 : jwt 编号 : oauth),可互换存储(in-memory, (中文(简体) ), filesystem, (中文(简体) ), Supabase, (中文(简体) ), Cloudflare KV/R2/D1),结构化记录,可选择的OpenTeleometry tracking.

古腾堡特有:

  • 搜索和浏览读取了本地SQLite+FTS5目录镜像. 当镜子冷的时候,搜索会回到 古滕德克斯语Name; 镜像所缺少的一本书从内容镜上的 RDF 记录读取
  • 从 Gutenberg 工程内容镜像中获取完整纯文本, 并带有 UTF-8/ HTML 倒置
  • 每个租户会缓存书本, 所以以后的块会读取跳过抓取
  • 不需要 API 密钥

方便代理输出 :

  • is_readable 旗帜 带有 UTF-8 纯文本的文本记录, 或者没有音频格式的 HTML; 缺少的镜像文件仍然返回 text_file_not_found
  • offset, (中文(简体) ), length, (中文(简体) ), totalChars, (中文(简体) ), remainingChars,以及 hasMore 支持可靠顺序读取
  • provenance 财务报告和审定财务报表 sourceFormat 每一文本答复都涉及归属和忠诚

开始

连接到主机实例, 没有安装 :

claude mcp add --transport http gutenberg-mcp-server https://gutenberg.caseyjhand.com/mcp

或者在当地运行它:

claude mcp add gutenberg-mcp-server -- npx -y @cyanheads/gutenberg-mcp-server

对于其他客户端,请将此添加到 MCP 配置文件中 :

{
  "mcpServers": {
    "gutenberg-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/gutenberg-mcp-server"]
    }
  }
}

不需要 API 密钥 。 对于 Docker 或源构建,请参见 运行服务器。 。 。 .


配置

变量说明默认
GUTENDEX_BASE_URLGutendex目录 API 基础 URL,当本地目录镜像无法回答时用于搜索和受欢迎浏览.https://gutendex.com/books/
GUTENBERG_TEXT_BASE_URL内容镜像服务 /cache/epub 文件树:书籍文本,批量目录存档,和每册目录记录.https://gutenberg.pglaf.org
GUTENBERG_MIRROR_PATHSQLite 目录路径;在容器中使用持续体积.$XDG_DATA_HOME/gutenberg-mcp-server/gutenberg-catalog.sqlite (单位:千美元)~/.local/share 何时 XDG_DATA_HOME 未设置、 空或相对)
GUTENBERG_MIRROR_REFRESH_CRON进程目录更新的 Cron 排程 .未设置
MCP_TRANSPORT_TYPE运输: stdio 或者说 http。 。 。 .stdio
MCP_SESSION_MODEHTTP 会话模式 : auto, (中文(简体) ), stateful,或 stateless覆盖 stateless 服务器声明的状态 createApp()。 。 。 .stateless
MCP_HTTP_PORTHTTP 服务器端口 .3010
MCP_AUTH_MODEAuth 模式 : none, (中文(简体) ), jwt,或 oauth。 。 。 .none
MCP_LOG_LEVEL日志级别(RFC 5424).info
LOGS_DIR日志文件目录(只有Node.js).<project-root>/logs
STORAGE_PROVIDER_TYPE存储后端.in-memory
OTEL_ENABLED启用 OpenTelemet 仪器。 。 。 .false

构建本地目录 npx -y @cyanheads/gutenberg-mcp-server mirror init 检查一下 mirror verify· ; mirror refresh 档案重建后重新收割。 每个都从任何目录和打印中运行在节点或 Bun 下 mirror path: <absolute path> 先说 从一个源检出, bun run mirror:init, (中文(简体) ), mirror:verify,以及 mirror:refresh 运行已建 dist/ (建设先行. 服务器在启动时从未收成,并回复了从Gutendex的搜索和从每本书的RDF记录中查看书籍,直到第一次收成完成. 随时更新目录 mirror refresh 在主机调度器上,或设置 GUTENBERG_MIRROR_REFRESH_CRON。 。 。 .

现有 ./.mirror/gutenberg-catalog.sqlite 仅在 GUTENBERG_MIRROR_PATH 点它。 空白或未替换 ${…} 中任何一个变量的值为未设置.


运行服务器

地方发展

要求数 Bun v 1.4.4 (单位:千美元) 或更高(或Node.js v24+).

  • 克隆并安装 :

    git clone https://github.com/cyanheads/gutenberg-mcp-server.git
    cd gutenberg-mcp-server && bun install
    cp .env.example .env   # optional overrides
    
  • 构建和运行 :

    # One-time build
    bun run rebuild
    
    # Run the built server
    bun run start:stdio
    # or
    bun run start:http
    
  • 运行检查和测试 :

    bun run devcheck   # Lint, format, typecheck, security
    bun run test       # Vitest test suite
    bun run lint:mcp   # Validate MCP definitions against spec
    

夹克

docker run --rm -p 3010:3010 ghcr.io/cyanheads/gutenberg-mcp-server:latest

图像默认为 HTTP 传输、 无国籍会话模式和日志到 /var/log/gutenberg-mcp-server运行到一个 MCP 客户端的 stdio,使用 "command": "docker" 与 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/gutenberg-mcp-server:latest"]为了在当地建设, docker build -t gutenberg-mcp-server .; OpenTeleometry 端点依赖性默认安装——用 --build-arg OTEL_ENABLED=false 以略去它们.


项目结构

目录目的
src/index.tscreateApp() 进入点——登记工具及其服务.
src/config/server-config.ts服务器特定环境变量剖析(Gutendex和内容-迷信URL,目录镜像路径和刷新时间表).
src/mcp-server/tools/definitions/工具定义*.tool.ts) (中文(简体) ).
src/services/gutendex/Catalog service——镜像读取,活出Gutendex搜索和浏览,每本作的RDF取景.
src/services/catalog-mirror/本地 SQLite+FTS5 目录镜像 – RDF 摄取,读取帮助器,以及 mirror CLI(英语:CLI).
src/services/gutenberg-text/完全的纯文字取回,锅炉板剥取,租户入洞,并分解.
skills/gutenberg-guide/出版的读取和发现工作流程的代理技能,也服务于MCP.
tests/单位和综合测试镜像 src/。 。 。 .

发展指南

见 CLAUDE.md 编号 : AGENTS.md 发展准则和建筑规则。 简本:

  • 搬运工投掷,框架渔获量——否 try/catch 在工具逻辑中
  • 使用 ctx.log 请求范围伐木, ctx.state 租户范围储存
  • 通过输入数组在 src/index.ts
  • 环绕外部 API 调用: 验证 生 → 规范到域类型 → 返回输出计划; 永远不要编织缺失的字段

捐款

问题值得欢迎。 提交前进行检查和测试:

bun run devcheck
bun run test

数据属性

数据来自 古腾堡项目 属于公有领域。 Catalog元数据来自Gutenberg项目RDF目录,为了进行现场搜索, 古滕德克斯语Name (麻省理工学院执照).


许可证

阿帕奇-2.0 — 见 自由主义 详细情况.

版本与发布记录

@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 是什么?

搜索、浏览和阅读Gutenberg项目78,000+公共域名书籍,通过MCP进行全文检索并抵消/限制块。 (原始内容存档于2012-10-12). STIO 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 和提交记录判断。