mcp-books

mcp-books

三座出色的档案馆保存着出版物的扫描记录，并各自用自己的方式对其进行描述。Internet Archive 保存任何人提交的书籍、电影、录音和软件，并已对其中数百万份进行光学字符识别。美国国会图书馆 按材料类型分别编目，发布美国的国家馆藏。data.bnf.fr 发布法国国家图书馆（Bibliothèque nationale de France）的规范记录，描述作品及其作者，而非作品的具体副本。

这个服务只需一个问题，就能查询这三座档案馆。你可以搜索扫描文档中的文字、搜索目录，还可以用统一格式读取记录，无论记录由哪座档案馆保存。无需 API 密钥，也无需账户。

Version française

---

安装

一键安装

Claude Code

claude mcp add books -- npx -y mcp-books

Claude Desktop、Cursor 以及使用标准配置格式的任何客户端

{
  "mcpServers": {
    "books": {
      "command": "npx",
      "args": ["-y", "mcp-books"]
    }
  }
}

需要 Node 24 或更高版本，无需设置任何环境变量。

使用 Docker

{
  "mcpServers": {
    "books": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-books:2.0.1"]
    }
  }
}

-i 会保持标准输入处于打开状态，协议通过它传输；省略 -t，因为 TTY 会改写数据流。容器只需能够通过 HTTPS 访问 archive.org、openlibrary.org、www.loc.gov 和 data.bnf.fr，除此之外别无所需：不需要卷、端口或凭据。

使用 Bundle，无需 npm

从最新版本下载 mcp-books-2.0.1.mcpb 并打开。支持 MCP bundles 的客户端会自行安装，无需 npm，也无需编辑配置文件。Bundle 包含其依赖项，因此安装时不会获取任何内容。

你可以这样提问

• “哪些书提到了 Beaumont 灯塔？”
• “帮我找找有关 1906 年旧金山地震的资料。”
• “读一下那条记录，并告诉我原件由谁收藏。”
• “BnF 有哪些关于那位作者的资料？”
• “搜索照片，而不是书籍。”

回答需要几秒钟：系统会查询三座档案馆，每座档案馆的响应速度各不相同。

三个来源

来源	馆藏	描述内容
archive	Internet Archive	各类存档副本
loc	美国国会图书馆	国家馆藏，每类对应一个目录
bnf	法国国家图书馆	作品及其作者

行中的 id 指明其所属的档案馆，因此从某个结果中读取的标识符会返回到正确的档案馆。 绝不会跨档案馆汇总数量，如果某个档案馆查询失败，报告会注明其查询失败，而不是没有找到结果。

工具

工具	功能
search_inside	搜索扫描文档中的文字。
search_items	按标题、创作者、主题或普通文字搜索目录。
get_item	以统一格式读取一条记录，无论其由哪个档案馆保存。

search_inside

搜索扫描文档中的文字，这些文字通过光学字符识别从页面中提取。

参数	类型	必需	功能
query	string，2 到 300 个字符	是	要在文档中查找的短语。
limit	integer，1 到 25，默认值为 3	否	每个档案馆保留的匹配项数。
page	integer，1 到 100，默认值为 1	否	匹配项的页码。
max_excerpt_chars	integer，80 到 1200，默认值为 300	否	返回的段落长度。
max_excerpts_per_match	integer，1 到 10，默认值为 2	否	每份匹配文档返回的段落数。
fan_out	boolean，默认值为 true	否	查询每个档案馆，而不是在首个档案馆响应后停止。
sources	来源 ID 数组	否	仅查询这些档案馆。

返回内容： hits，其中每项包含 id，可供 get_item 使用，并指明其所属档案馆；source 和 source_name；不带前缀的档案馆自身 identifier；title、creator 和 year；档案馆注明的 page_number；excerpts；以及 excerpt_kind。

excerpt_kind 决定摘录的价值。 passage 是匹配文字周围的文本。page_opening 是页面开头部分：由于档案馆返回的机器识别文本在匹配文字出现之前就已截断，因此系统会返回该部分；它不包含匹配内容，所以引用它就等于引用了其他内容。同一匹配项的所有摘录类型都相同。

search_items

搜索目录。

Argument	Type	Required	What it does
query	string, 1 to 300 characters	yes	标题、创作者、主题或普通词语。
media_type	a kind one of the archives holds	no	要搜索的资料类型。
year_from	integer, 1000 to 2100	no	起始年份。
year_to	integer, 1000 to 2100	no	截止年份。
sort	relevance, newest, oldest or title, default relevance	no	结果的排序方式。
limit	integer, 1 to 25, default 5	no	每个档案保留的结果数。
page	integer, 1 to 100, default 1	no	结果页码。
fan_out	boolean, default true	no	查询所有档案。
sources	array of source ids	no	仅查询这些档案。

这三个档案对资料的分类方式各不相同。若未指定类型，Internet Archive 会同时搜索所有类型；美国国会图书馆按类型分别提供检索途径，因此未指定类型的搜索会注明读取的是哪一种类型；BnF 的搜索则查询作品。若某个档案不识别指定的 media_type，就会跳过该档案，并在答复中说明。

**返回内容：**符合结果条目格式的记录，以及 per_source 字段，其中包含每个档案的一份报告：其 status、贡献的 count、reported_total，以及说明该数字所统计内容的 reported_total_means。

get_item

读取一条记录，并统一为同一种格式，无论该记录由哪个档案保存。

Argument	Type	Required	What it does
identifier	string, 1 to 500 characters	yes	结果条目携带的 id。
sections	array of description, subjects, copies, context, default ["description"]	no	要返回的部分。
max_copies	integer, 1 to 50, default 10	no	要列出的副本数。
text_offset	integer, 0 to 1000000, default 0	no	文本的续读位置。
max_text_chars	integer, 200 to 8000, default 1500	no	要提供的文本量。

**返回内容：**记录及其 id、source 和 source_name，档案自身的 identifier、title、creator，按原样发布的 date，以及 year 和 year_means；后者说明该年份对应的事件，因为三个档案对记录日期的标注方式各不相同。attribution 是档案要求注明的来源信息；identifier_provisional 用于说明该标识符是生成的而非读取的，让调用方知道它可能无法解析。

答案对档案的说明

每个答案都会分别说明每个档案的情况。一个档案请求失败、一个无人查询、一个返回空结果，这是三种不同的情况，报告时也会分别列出。总数始终与发布该总数的档案并列，并说明该档案所说的总数统计的是什么：一个统计文档，另一个统计报纸版面。

扫描文本的价值

扫描文档中的文字是通过光学字符识别从页面提取的。摘录会保留这一过程中的误读，并按识别结果原样提供，不做更正。引用时请注明这是扫描文本，并链接到记录，以便读者查看页面。

配置

所有变量都是可选的。在客户端配置的 env 块中设置它们。

变量	默认值	作用
BOOKS_USER_AGENT	项目标识	向三个档案标识你的应用程序，并提供可供联系的地址。
BOOKS_MIN_INTERVAL_MS	每个档案各自的请求间隔	扩大向同一档案发送两次请求之间的间隔，范围为 500 到 60000。若未设置，每个档案都会保持其公布的请求间隔；此处设置的数值仅在间隔更长时生效。
BOOKS_TIMEOUT_MS	45000	单次请求的截止时间，范围为 1000 到 120000。
BOOKS_MAX_RETRIES	3	发生暂时性故障后重试的次数，范围为 0 到 8。
BOOKS_CACHE_TTL_MS	900000	答案在内存中的保留时长，范围为 0 到 86400000。
BOOKS_CACHE_MAX_ENTRIES	200	内存中同时保留的答案数，范围为 1 到 5000。
BOOKS_LOG_LEVEL	error	日志级别：silent、error、info 或 debug，写入 stderr。

超出范围的值会回退为默认值，相关原因会写入 stderr。

错误

每种失败都会附带六种代码之一、一条消息，以及在有帮助时说明下一步操作的提示。

Code	发生了什么	如何处理
not_found	档案库已响应，但没有这条记录。	使用 search_items 检查标识符。
invalid_input	请求发出前，参数已被拒绝。	阅读消息，其中会指出具体参数。
rate_limited	档案库要求此客户端放慢请求速度。	等待后使用相同参数再次调用。记录仍然存在。
parse_failure	收到的响应格式无法被此客户端读取。	在问题跟踪器中报告。
network_error	请求未能完成。	稍后重试。
timeout	请求超出了截止时间。	提高 BOOKS_TIMEOUT_MS，或减少请求的行数。

失败的档案库会单独报告，不会导致整个响应失败，因此某个档案库没有响应时，不会隐藏其他档案库的结果。

作为库使用

用于读取三个档案库的这一层会独立发布，自带请求节奏、缓存和错误处理，且不附带任何协议。

import { BooksClient } from "mcp-books/client";

const client = new BooksClient();
const read = await client.searchItems({ query: "beaumont light-house", limit: 3 });
console.log(read.data.rows.length);

每次读取都会返回 { data, cached }，并会抛出携带六种代码之一的错误。每个档案库都有自己的请求节奏，此处也会遵守其最低间隔。

请求节奏与来源标注

每个档案库的请求都会单独限速，每次只发送一个请求，并以该档案库自身的最低间隔和配置间隔中较大的值为准：美国国会图书馆公布的间隔最慢，因此同时请求三个档案库时，每个档案库只会收到一个请求，而不是三个请求。User-Agent 始终以项目标识和可供联系的地址结尾。

每条记录都会附带其页面地址，以及档案库要求的 attribution。Internet Archive 中的条目归其存放者所有；美国国会图书馆的记录会注明其自身的权利信息；BnF 则要求在展示其元数据的任何地方注明来源和检索日期。

此 MCP 服务是一个非官方项目，与它读取的任何档案库均无关联。

隐私

此服务不会收集任何关于你的信息，也不会向作者发送任何内容。它在你的计算机上运行，只会联系 archive.org、openlibrary.org、www.loc.gov 和 data.bnf.fr，不会联系其他地址；运行期间会将响应保存在内存中，不会写入磁盘。PRIVACY.md 说明了请求会携带哪些信息，以及哪些设置会改变这些信息。

开发

npm install
npm run build:fixtures
npm test
npm run check

测试使用生成的测试样例运行，不会发起网络请求。实时测试套件 npm run test:live 会为每条路由发送一个请求，并在每晚直接对这些档案库运行。

贡献

漏洞、问题和想法都可以提交到问题跟踪器。欢迎提交拉取请求；先提出问题有助于就变更方案达成一致。请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。记录归发布它们的档案库及其存放者所有。

---

mcp-books（法语版）

英文版

三大档案馆保存着已出版内容的数字化记录，并各自用自己的方式描述这些内容。Internet Archive 保存人们上传的书籍、电影、录音和软件，并已对数百万份资料进行了光学字符识别。 Library of Congress 发布美国国家馆藏，按文献类型编制目录。 data.bnf.fr 发布法国国家图书馆的规范记录，这些记录描述的是作品及其作者，而不是馆藏副本。

这个服务只需一个问题，就能查询这三大档案馆。你可以搜索数字化文档中的文字、搜索目录，并以统一格式读取记录，无论记录来自哪个档案馆。无需 API 密钥，也无需账户。

安装

一键安装

Claude Code

claude mcp add books -- npx -y mcp-books

Claude Desktop、Cursor 及所有使用标准配置格式的客户端

{
  "mcpServers": {
    "books": {
      "command": "npx",
      "args": ["-y", "mcp-books"]
    }
  }
}

需要 Node 24 或更高版本，且无需设置环境变量。

使用 Docker

{
  "mcpServers": {
    "books": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-books:2.0.1"]
    }
  }
}

-i 会让标准输入保持打开状态，它是协议通信通道；省略 -t，因为 TTY 会重写数据流。容器需要通过 HTTPS 访问 archive.org、openlibrary.org、www.loc.gov 和 data.bnf.fr，除此之外不需要任何东西：无需卷、端口或凭据。

Bundle，无需 npm

从最新发布版本下载 mcp-books-2.0.1.mcpb，然后打开它。支持 MCP bundle 的客户端会自动完成安装，无需 npm，也无需修改配置文件。Bundle 包含其依赖项，因此安装时不会下载任何内容。

可以这样提问

• “有哪些书提到了 Beaumont 灯塔？”
• “帮我查找关于 1906 年旧金山地震的资料。”
• “读一下这条记录，告诉我原件由谁保存。”
• “法国国家图书馆收藏了哪些关于这位作者的资料？”
• “请搜索照片，而不是书籍。”

回答需要几秒钟：三个档案馆会按各自的速度进行查询。

三个来源

来源	档案馆	描述内容
archive	Internet Archive	各类捐赠馆藏副本
loc	Library of Congress	国家馆藏，按文献类型编制目录
bnf	法国国家图书馆	作品及其作者

每一行的 id 都标明其所属档案馆，因此可以根据回答中的标识符返回相应档案馆。不同档案馆的数量绝不会相加；如果某个档案馆查询失败，会明确报告失败，而不会说成没有找到结果。

工具

工具	功能
search_inside	在扫描文档中查找包含的词语。
search_items	按标题、作者、主题或简单关键词在目录中查找。
get_item	以统一格式读取一条记录，无论它来自哪个档案库。

search_inside

在扫描文档中查找文本，该文本来自光学字符识别。

参数	类型	必填	功能
query	字符串，2 至 300 个字符	是	要在文档中查找的短语。
limit	整数，1 至 25，默认值为 3	否	每个档案库保留的匹配项数量。
page	整数，1 至 100，默认值为 1	否	要查看的匹配项页码。
max_excerpt_chars	整数，80 至 1200，默认值为 300	否	返回的文本片段长度。
max_excerpts_per_match	整数，1 至 10，默认值为 2	否	每个匹配文档返回的文本片段数量。
fan_out	布尔值，默认值为 true	否	查询每个档案库，而不是在第一个响应的档案库处停止。
sources	来源 ID 数组	否	仅查询这些档案库。

返回内容： hits，每个匹配项都包含 id，供 get_item 使用并用于标识其档案库；包含 source 和 source_name；档案库自身的 identifier（不含前缀）；title、creator 和 year；档案库提供页码时的 page_number；excerpts；以及 excerpt_kind。

excerpt_kind 决定了摘录的含义。 passage 是包含匹配词语的上下文文本。page_opening 是页面开头的内容；之所以返回它，是因为档案库提供的机器可读文本在这些词语出现之前就结束了：它不包含匹配内容，因此引用它就等于引用了其他内容。同一匹配项的所有摘录类型都相同。

search_items

在目录中搜索。

参数	类型	必填	说明
query	字符串，1 到 300 个字符	是	标题、作者、主题或简单词语。
media_type	某个档案馆所持有的一种类型	否	要搜索的文档类型。
year_from	整数，1000 到 2100	否	最早年份。
year_to	整数，1000 到 2100	否	最晚年份。
sort	relevance、newest、oldest 或 title，默认值为 relevance	否	行的排序方式。
limit	整数，1 到 25，默认值为 5	否	每个档案馆保留的行数。
page	整数，1 到 100，默认值为 1	否	要显示第几页的行。
fan_out	布尔值，默认值为 true	否	查询每个档案馆。
sources	来源标识符数组	否	仅查询这些档案馆。

三个档案馆对藏品的划分方式各不相同。未指定类型时，Internet Archive 会同时搜索所有类型；Library of Congress 按类型提供路由，因此未指定类型的搜索会告知读者查询了哪种类型；而 BnF 会搜索作品。如果某个档案馆没有 media_type 所指的类型，则该档案馆会从响应中排除，响应也会说明这一点。

**返回：**采用 hit 格式的行，以及 per_source，其中包含各档案馆的报告：其 status、提供的 count、reported_total，以及说明该档案馆如何计算此数字的 reported_total_means。

get_item

无论记录由哪个档案馆持有，均以统一格式读取记录。

参数	类型	必填	说明
identifier	字符串，1 到 500 个字符	是	某一行所带的 id。
sections	description、subjects、copies、context 数组，默认值为 ["description"]	否	要返回的部分。
max_copies	整数，1 到 50，默认值为 10	否	要列出的副本数。
text_offset	整数，0 到 1000000，默认值为 0	否	从文本的哪个位置继续。
max_text_chars	整数，200 到 8000，默认值为 1500	否	返回的文本长度。

**返回：**记录及其 id、source 和 source_name、档案馆专属的 identifier、title、creator、按发布时原样保留的 date，以及附有 year_means 的 year，用于说明该年份代表什么，因为三个档案馆对记录的定年方式各不相同。attribution 是该档案馆要求注明的归属信息；identifier_provisional 则用于说明标识符是否为构造而非读取所得，以便调用方知道它可能无法解析。

一条响应说明了档案馆的什么情况

每条响应都会分别报告每个档案馆的情况。一个请求失败、一个无人查询和一个返回空结果，是三种不同的情况，因此会分别报告。总数会与发布该总数的档案馆并列，并说明该档案馆统计的内容：一个统计文档，另一个统计日志页。

数字化文本的价值

数字化文档中的文字来自光学字符识别。摘录会保留这一过程产生的识读错误，并按识读结果原样提供，而不是经过修正。引用时请注明这是数字化文本，并链接到记录，以便读者查看页面。

配置

每个变量都是可选的。请将它们设置在客户端配置的 env 块中。

变量	默认值	功能说明
BOOKS_USER_AGENT	项目标识	向三个档案馆标识你的应用，并提供联系相关人员的地址。
BOOKS_MIN_INTERVAL_MS	每个档案馆各自的频率	将向同一档案馆发送两次请求的间隔延长至 500 到 60000。若未设置，每个档案馆会沿用其公布的频率；若在此设置了值，则只在该值更长时生效。
BOOKS_TIMEOUT_MS	45000	请求超时时间，范围为 1000 到 120000。
BOOKS_MAX_RETRIES	3	临时失败后的重试次数，范围为 0 到 8。
BOOKS_CACHE_TTL_MS	900000	响应在内存中的保留时长，范围为 0 到 86400000。
BOOKS_CACHE_MAX_ENTRIES	200	同时保存在内存中的响应数量，范围为 1 到 5000。
BOOKS_LOG_LEVEL	error	silent、error、info 或 debug，写入错误输出。

超出范围的值会恢复为默认值，原因会写入错误输出。

错误

每个失败都带有六种代码之一、一条消息，以及在有帮助时提供的下一步操作提示。

Code	发生了什么	该怎么做
not_found	某个档案有响应，但其中没有这条记录。	使用 search_items 检查标识符。
invalid_input	在发出任何请求之前，参数就被拒绝了。	阅读消息，其中会指出相关参数。
rate_limited	某个档案要求此客户端放慢速度。	等一会儿，然后使用相同参数重试。这条记录仍然存在。
parse_failure	收到了响应，但其格式在这里无法读取。	请在问题跟踪页报告。
network_error	请求未能完成。	稍后重试。
timeout	请求超时。	增加 BOOKS_TIMEOUT_MS，或减少请求的行数。

某个档案发生故障时，会逐个报告档案，而不会导致整个响应失败，因此一个无响应的档案不会隐藏其他档案。

作为库使用

读取这三个档案的层单独发布，有自己的节奏、缓存和错误处理，不附带协议。

import { BooksClient } from "mcp-books/client";

const client = new BooksClient();
const read = await client.searchItems({ query: "beaumont light-house", limit: 3 });
console.log(read.data.rows.length);

每次读取都会返回 { data, cached }，并抛出带有六种代码之一的错误。每个档案都有自己的节奏，其最小间隔在这里同样适用。

节奏与署名

每个档案都单独限速，一次只发出一个请求；起作用的是该档案自身的最小间隔与配置间隔中的较大值：Library of Congress 公布的最慢，因此同时查询三个档案，对每个档案来说都是一次请求，而不是三次。User-Agent 始终以项目标识和联系人员的地址结尾。

每条记录都带有其页面地址，以及档案要求的 attribution。Internet Archive 的文档归提交者所有，Library of Congress 的记录会说明自身权利，而 BnF 要求在任何展示其元数据的地方标明来源和检索日期。

此 MCP 是一个非官方项目，与其读取的任何档案均无关联。

隐私

此服务不会收集你的任何信息，也不会向作者发送任何内容。它在你的计算机上运行，只连接 archive.org、openlibrary.org、www.loc.gov 和 data.bnf.fr，在运行期间将响应保留在内存中，也不会向磁盘写入任何内容。PRIVACY.md 说明了请求会携带哪些信息，以及哪些设置会改变这些行为。

开发

npm install
npm run build:fixtures
npm test
npm run check

测试使用生成的 fixtures 运行，不会发出任何请求。实时测试套件 npm run test:live 会为每条路由发出一个请求，并且每晚直接对这些档案运行。

贡献

错误报告、问题和想法都可以提交到问题跟踪页。欢迎提交修改建议；先开一个议题有助于就修改方式达成一致。请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。记录归发布它们的档案和提交者所有。