openlibrary-mcp-server

---

概述

Open Library 收录了 2,000 多万册书籍、版本、作者和主题，并提供 Internet Archive 扫描书籍的全文搜索功能。您可以搜索和浏览目录，从作品深入查看其版本，或从作者深入查看其作品，还可以构建封面图片 URL。

工具

工具	描述
openlibrary_search_books	使用字段筛选器（标题、作者、主题、出版商、ISBN、语言）搜索目录，提供由服务提供方选择的版本、分页功能，以及可选的实时阅读可用性
openlibrary_get_work	按 Open Library Work ID（OL…W）获取作品——标题、描述、主题、封面 ID 和作者 ID
openlibrary_get_editions	列出作品的各个版本——出版商、语言、格式、ISBN 和印次详情
openlibrary_get_edition	每次调用最多解析 50 个不同标识符，支持 ISBN-10、ISBN-13、OCLC、LCCN 或 Open Library Edition ID（OL…M），并报告未匹配和未处理的标识符
openlibrary_search_authors	按姓名搜索作者——返回作者 ID、出生和逝世日期、代表作品及主题关联
openlibrary_get_author	按 Open Library Author ID（OL…A）获取作者详情——简介、日期、照片 ID，以及来自 Wikidata、VIAF、ISNI、Goodreads 和 LibraryThing 的关联标识符
openlibrary_get_author_works	列出作者的作品——标题、封面 ID 和 Work OLID，可据此进一步查看版本或详情
openlibrary_get_subject	按主题标签浏览作品——返回匹配的作品及其版本数、封面 ID，以及作品总数
openlibrary_search_inside	在 Internet Archive 图书的扫描文本中进行全文搜索——返回匹配条目及摘要片段
openlibrary_get_cover_url	获取图书封面图或作者照片的 S/M/L 尺寸图片 URL——返回可嵌入 Markdown 的直接 HTTPS URL

资源

资源	描述
openlibrary://works/{work_id}	按 Open Library Work ID 获取作品详情——标题、描述、主题、封面 ID 和作者 ID，可作为注入上下文使用
openlibrary://authors/{author_id}	按 Open Library Author ID 获取作者详情——姓名、简介、日期、照片 ID 和关联的外部标识符，可作为注入上下文使用

这两种资源提供的数据也可通过 openlibrary_get_work 和 openlibrary_get_author 获取，适用于不展示 MCP 资源的客户端。

Agent 技能

openlibrary-guide 涵盖版本选择、书目解析、段落识别和不完整的元数据。该技能包含在 npm、Docker 和桌面应用程序包中，并通过 MCP 技能发现和 skill:// 资源提供。

功能参考

分页工具每次调用最多返回 100 行。超出此限制的较大正整数会被限制到上限，并提示实际采用的上限和下一偏移量。OPENLIBRARY_CLAMP_LIMITS=false 可恢复对超过 100 的值进行架构校验的行为。文本和结构化输出包含相同的完整领域数据，包括数组和数值精度。

openlibrary_search_books _工具

• 支持使用 Solr 字段前缀（title:、author:、subject:、publisher:、isbn:、language:）或专用筛选参数进行全文查询；每页返回 1–100 条结果（默认 10 条），支持偏移量分页
• sort：relevance（默认）、new、old、rating、editions
• language 接受 3 个字母的 MARC 代码或可转换的 2 个字母 ISO 代码；无法转换的 2 个字母代码会导致 unknown_language_code 错误，而不会被静默忽略
• include_availability 会添加 Internet Archive 的实时借阅/阅读状态（延迟约 200 毫秒），默认关闭；Open Library 未提供的标志会被省略，而不会报告为 false；availability: null 表示该作品没有返回任何可用性信息
• 返回作品级记录，包括版本数、封面 ID、主题和 Internet Archive 标识符
• 可选的 matching_edition 和 matching_edition_count 会保留 Search API 选定的版本及匹配数量。所选版本由服务提供方排序确定；这并不能证明所有未指定字段的搜索词都与该版本匹配
• invalid_search_query 会报告上游 HTTP 422 校验错误，并提供恢复指引；仍支持带有特定筛选条件的空查询

---

openlibrary_get_work _工具

• 通过 Open Library Work ID（OL…W）获取，可选 /works/ 前缀；其他任何内容——ISBN、版本或作者 OLID——都会在发起请求前因输入验证失败，并指出从 ISBN 获取其作品的途径是使用 openlibrary_get_edition（id_type: "isbn"）
• 返回标题、描述、主题（以及地点／时间／人物分类）、封面 ID 和作者 ID——不包含作者姓名（请使用 openlibrary_get_author 或 openlibrary_search_books）
• 合并后的 Work ID 仍可访问——系统会沿重定向链获取规范记录，work_id 会报告规范 ID；如果两个 ID 不同，补充信息通知会同时列出这两个 ID
• 如果 Work ID 不存在，或其重定向链最终没有指向任何作品，则返回 not_found

---

openlibrary_get_editions _工具

• 通过 Work ID（OL…W）列出作品的版本，可选 /works/ 前缀；每页 1–100 条（默认 10 条），使用偏移量分页，输出中会回显请求的 offset
• work_id 验证规则与 openlibrary_get_work 相同——通过 openlibrary_get_edition（id_type: "isbn"）将 ISBN 解析为其作品
• 返回 ISBN-10/13、出版商、语言、页数、封面 ID 和版本 OLID（OL…M）；如果有记录，还会返回 physical_format 和 edition_name
• 合并后的 Work ID 仍可访问——规范作品的版本会以其 ID 作为 work_id 返回，并附带同时列出两个 ID 的补充信息通知；对于仍存在的作品，只需一次请求
• 如果 Work ID 不存在，或其重定向链最终没有指向任何作品，则返回 not_found

---

openlibrary_get_edition _工具

• 接受 1–1,000 个输入字符串，去重完全相同的字符串，并在一次上游批处理中处理前 50 个不同的标识符；其余标识符会作为 unprocessed 返回，以便重新提交。所有标识符共用一个 id_type：isbn（10 或 13 位数字，ISBN-10 的校验位可以是 X）、oclc（数字）、lccn（不进行校验）或 olid（OL…M）。当 OPENLIBRARY_CLAMP_LIMITS=false 时，输入数组最多包含 50 个条目
• 部分成功：成功解析的标识符会按请求顺序返回在 editions 中；其余标识符会列入 unresolved，并标记为 invalid_identifier（格式错误，未发送至上游）或 not_found（格式正确，但没有记录）——只有在没有任何标识符成功解析时，调用才会失败
• 如果 Open Library 的批量查询本身失败，则返回可重试的 upstream_unavailable——包括速率限制以外的 HTTP 错误状态，或 HTML 页面——因此上游服务中断绝不会被误报为版本缺失
• 作者信息会内联返回——包括版本自身的署名，或在版本本身未列出作者时从父作品中找回并标记为 source: "work" 的作者；如果这些查询失败，批处理仍会返回，并通过补充信息通知指出缺少作者信息或仅显示作者 ID 的版本
• 返回 ISBN-10/13、OCLC、LCCN、LC 索书号、出版商、所有已编目的 languages、页数、封面 ID、父作品 ID，以及存在时的 Internet Archive ebook_url。单数形式的 language 仍为第一个已编目的语言；如果目录中有 physical_format 和 edition_name，则保留其原有措辞
• 如果所有已处理的标识符都未能解析，现有的类型化错误也会在其数据和恢复提示中包含每个 unprocessed 标识符

---

openlibrary_search_authors _工具

• 按姓名搜索——可匹配部分姓名和别名；每页 1–100 条（默认 10 条），使用偏移量分页
• 返回作者 ID（OL…A）、别名、出生／去世日期、代表作品、作品数量、热门主题和平均评分

openlibrary_get_author _工具

• 按作者 ID（OL…A）获取；会移除开头的 /authors/ 前缀
• 返回简介、出生/逝世日期、照片 ID，以及关联标识符（Wikidata、VIAF、ISNI、Goodreads、LibraryThing）
• 合并后的作者 ID 仍可访问——响应会返回规范记录；如果规范 ID 与请求的 ID 不同，还会在补充说明中列出规范 ID
• 当作者 ID 不存在、指向的记录不是作者（而是作品或版本 OLID），或其重定向链中没有作者时，返回 not_found

---

openlibrary_get_author_works _工具

• 按作者 ID（OL…A）列出作品；每页 1–100 项（默认 20），使用偏移量分页，并在输出中回显请求的 offset
• 每项作品返回标题、首次出版日期、封面 ID 和作品 ID（OL…W）
• 合并后的作者 ID 仍可访问——如果规范 ID 与请求的 ID 不同，补充说明会列出规范 ID
• 当作者 ID 不存在、指向的记录不是作者（而是作品或版本 OLID），或其重定向链中没有作者时，返回 not_found

---

openlibrary_get_subject _工具

• 主题名称会去除首尾空格、转换为小写，并将空白规范化为下划线；每页 1–100 项（默认 12），使用偏移量分页，并在输出中回显请求的 offset
• 空白输入会在发出任何请求前返回 invalid_subject
• 返回规范主题名称、规范化后的主题键、作品总数，以及每部作品的作者姓名、版本数量和封面 ID
• 结果为空时会附带恢复提示，建议尝试不同词形、同义词或更宽泛的术语——主题标签由用户贡献，且不一致

---

openlibrary_search_inside _工具

• 在 Internet Archive 扫描书籍文本中进行全文搜索——这是唯一能回答“哪本书包含这段文字？”的工具；精确匹配时请将短语加引号，不加引号的词会分别匹配
• 使用实时索引通常需要 10–30 s，远超元数据工具；请审慎使用，不要将其作为通用书籍搜索
• 每页 1–100 条结果（默认 10），使用偏移量分页；每条结果都包含相关性分数，该分数只能在其所属结果集中比较
• 结果以 Internet Archive 的 ia_identifier 为键，而非 Open Library 作品 ID——将其与 openlibrary_search_books 返回的 ia_identifiers 匹配，以找到目录记录
• 当索引未返回结果集时，会返回可重试的 upstream_unavailable，因此搜索失败不会被误认为“没有书籍包含这段文字”

---

openlibrary_get_cover_url _工具

• 根据 id（数字）、isbn（10 或 13 位数字，ISBN-10 的校验位可以是 X），或 olid（target: "book" 时为 OL…M，target: "author" 时为 OL…A）解析封面或作者照片 URL；size 可设为 S/M/L（默认 M）
• 标识符会在发出任何请求前于本地验证——路径分隔符、.. 和控制字符会导致 invalid_identifier；通过 isbn 查询作者会导致 invalid_target
• 该工具只构造 URL，不会获取对应内容；返回 URL 并不代表封面确实存在
• 输出的 URL 可直接嵌入为 ![cover](url)

---

openlibrary://works/{work_id} _资源

• 与 openlibrary_get_work 返回相同字段，以可注入对话的 application/json 上下文形式提供，适用于讨论特定书籍
• work_id 来自 openlibrary_search_books 或 openlibrary_get_author_works；合并后的 ID 会解析到规范作品，并在返回的 work_id 中给出其 ID；如果 ID 指向的不是作品（而是版本或作者 OLID），则视为未找到

---

openlibrary://authors/{author_id} _资源

• 与 openlibrary_get_author 返回相同字段，以可注入对话的 application/json 上下文形式提供，适用于讨论特定作者
• author_id 来自 openlibrary_search_authors；合并后的 ID 会解析到规范作者，并在返回的 author_id 中给出其 ID；如果 ID 指向的不是作者（而是作品或版本 OLID），则视为未找到

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

Open Library 专属功能：

• 支持 Open Library 的 Search、Search Inside（全文）、Books、Authors 和 Subjects API，构建封面 URL，并查询 Internet Archive 的可用性
• 支持 Work → editions 和 author → works 深入查询，并在工具输出之间明确提供 OLID 交叉链接
• 可配置 User-Agent 请求头（OPENLIBRARY_USER_AGENT），按照 Open Library 的屏蔽机器人惯例标识服务
• 批量解析版本：一次上游调用最多处理 50 个 ISBN/OCLC/LCCN/OLID 标识符，并逐个报告部分失败
• 根据端点类别设置超时（记录查询为 10 s，搜索为 30 s，全文搜索为 45 s），并在 50 s 重试预算内等待。这样，上游响应较慢时会继续等待；上游出错时，会在典型的 60 s 客户端超时前返回分类错误；网关错误不会在循环中反复重试

便于 Agent 使用的输出：

• 每个空结果都提供恢复指引：回显搜索条件，并建议如何放宽查询条件或重试哪个偏移量
• 合并记录说明：openlibrary_get_author、openlibrary_get_author_works、openlibrary_get_work 和 openlibrary_get_editions 会跟随合并重定向；如果请求的 ID 已被合并，则通过补充通知显示规范 ID
• 逐项报告部分失败：openlibrary_get_edition 会返回已解析的版本和带类型的 unresolved 原因，而不会导致整个批次失败
• 提供完整文本和结构化输出，并在两种形式中保留截断与恢复通知

开始使用

将托管服务添加到 Claude Code——无需 API 密钥：

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

或者在本地运行：

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

对于其他客户端，请将以下内容添加到 MCP 配置文件：

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

有关 Docker 或从源代码构建的信息，请参阅运行服务。

配置

变量	说明	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_ENDPOINT_PATH	MCP 服务挂载的 HTTP 端点路径	/mcp
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。覆盖 src/index.ts 中声明的 stateless。	stateless
MCP_PUBLIC_URL	用于 TLS 终止反向代理部署的公共源地址覆盖值	无
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）	info
MCP_GC_PRESSURE_INTERVAL_MS	选择启用的、仅限 Bun 的强制 GC 压力循环（毫秒）。如果观察到堆增长，建议从 60000 开始。	0（已禁用）
LOGS_DIR	日志文件目录（仅限 Node.js）	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OPENLIBRARY_USER_AGENT	随所有 Open Library API 请求发送的 User-Agent。请按照社区惯例提供联系邮箱。	openlibrary-mcp-server [email protected]
OPENLIBRARY_CLAMP_LIMITS	将页面限制截断为 100，并处理前 50 个不同的版本标识符，其余部分将返回。设为 false 可恢复严格输入边界：100 行和 50 个原始标识符。	true
OTEL_ENABLED	启用 OpenTelemetry	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

需要 Bun v1.4.0 或更高版本（或 Node.js ≥ 24.0.0）。

• 克隆并安装：

  git clone https://github.com/cyanheads/openlibrary-mcp-server.git
  cd openlibrary-mcp-server && bun install
  cp .env.example .env   # optional overrides; no required variables
  

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  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/openlibrary-mcp-server:latest

该镜像默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/openlibrary-mcp-server。若要通过 MCP 客户端使用 stdio 运行，请使用 "command": "docker" 和 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/openlibrary-mcp-server:latest"]。若要在本地构建，请运行 docker build -t openlibrary-mcp-server .；默认会安装 OpenTelemetry 对等依赖项。构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点，用于注册工具和资源。
src/config	使用 Zod 解析并验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）——涵盖搜索、图书、作者、主题和封面，共 10 个工具。
src/mcp-server/resources	资源定义（*.resource.ts）——作品和作者。
src/services/open-library	Open Library 服务层——API 客户端和领域类型。
skills/	已发布的 Agent 指南，也可通过 MCP 技能发现功能提供。
tests/	单元测试和集成测试，结构与 src/ 对应。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 createApp() 数组中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；不要捏造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。