ndl-mcp

一个用于检索日本国立国会图书馆运营的国立国会図書館サーチ（NDL Search）的 MCP 服务器，基于 SRU searchRetrieve 接口。

这是继 cinii-mcp 和 jstage-mcp 之后的第三个同类项目，并共享其响应信封结构：类型化查询和脚本、匹配模式、渐进式广度、逐项 matched_in、类型化诊断、可记录的收据、署名。

运行之前

无需任何凭据。 NDL 搜索 API 是开放的。没有 API 密钥、没有应用程序 ID、没有令牌，无需在配置文件中粘贴任何内容。如果你在等待某样东西到达后才能使用本工具，那么你等待的东西不会到来。

但仍有一项义务。 APIのご利用について 第 17 条要求持续使用 API 的用户通过申请表报告其联系方式和用途——「事前の利用申請の要否にかかわらず」，无论是否要求事先提交使用申请。正式的利用申請仅对营利性使用有要求；而通知义务适用于所有持续访问的用户。

由于访问并不以提交申请为前提，世界上没有任何东西能阻止你跳过它。所以 install.ps1 会阻止你：在通知被记录之前拒绝注册服务器，并将日期写入 NDL-API-NOTIFICATION.txt。

.\install.ps1 -NotificationFiled 2026-08-19

不带该标志运行它会打印表单 URL，提供打开选项，然后退出。

Related MCP server: jp-lit-mcp

服务器不会做什么

以下承诺已提交给 NDL。它们是已实现的，而非仅作为愿景，安装程序的冒烟测试断言了前三项：

更改其中任何一项，就是在更改向国家图书馆申报的内容。请先提交补充通知。

数据提供方

只有申请中声明的五个数据集可访问。全部由 NDL 创建，采用 CC BY 许可，且均无需使用申请：

ndl-dl 和 ndl-dl-online——更广泛的数字馆藏——在提供方列表上标记为 △，需要尚未提交的申请。请求指定这些数据集会在进程内被拒绝，并返回 DPID_NOT_PERMITTED 诊断，而非发送出去。

工具

搜索字段：title、creator、publisher、subject、anywhere、ndc、isbn、issn、from_year、to_year。它们以 AND 组合；title、creator、publisher 和 subject 为部分匹配，ndc 为前缀匹配，标识符为精确匹配。

ndl_get_record 是一次获取操作，因此其信封省略了 searched_for——因为没有选择任何检索词。

两个会咬人的坑

搜索词中出现大写的 AND、OR 或 NOT 会导致 NDL 拒绝整个查询。 不是"返回零结果"——而是拒绝。该规则区分大小写，正如规范所述：War AND Peace 会被拦截，War and Peace 则通过。服务器在发送前进行检查，并返回 RESERVED_WORD_IN_QUERY 诊断，指明违规字段，而不是让图书馆以解析失败来回应。

NDL 执行一个它不愿量化的速率限制，并以 HTTP 429 回应。 帮助页面只说「同時リクエスト数には制限を設けています」，拒绝公布具体数字。在 2026 年 8 月 19 日的测试中，在远低于每秒一个持续请求的情况下就收到了 429——因此向图书馆申报的一秒下限是最低要求，而非保证。一次 429 会触发一次退避，遵循 Retry-After，然后服务器停止而不是继续施压。它报告 RATE_LIMITED，刻意与 API_ERROR 区分，因为两者对读者意味着不同的事情：被限流的搜索结果是未知的，而非空结果，绝不能写成不存在。

罗马化检索词会返回不足的结果。 NDL Search 以日文假名索引日文记录。对日文语料库使用拉丁字母查询就是罗马字陷阱，信封会为此引发 SCRIPT_LATIN_QUERY。searched_for 标题的存在是为了让助手实际选择的检索词显示在响应顶部而非被埋没——这就是该字段的全部意义，也是披露可以报告搜索所用检索词的原因。

收据

mediation.emit() 将每个响应信封写入位于 MCP_RECEIPT_LOG 的仅追加、哈希链式账本，install.ps1 将其设置为其他服务器使用的同一文件。取消设置该变量则什么都不写入，也不会失败。

请注意账本保存什么和不保存什么：查询、规范化检索词、发送的参数、时间戳、查询和参数的 SHA-256 哈希，以及返回记录的标识符。它不保存书目记录本身。记录查询不是积累数据库，不积累的承诺不会被保留收据所违反——但这一区别值得明确说明而非默认成立，因为从外部看两者很相似。

为什么只用 SRU

申请声明了 SRU 和 OpenSearch。本服务器仅实现 SRU，这比声明的少，因此是安全的——你总是可以使用比你告诉图书馆的更少的功能。

原因是证据性的。OpenSearch 响应格式未在第 1.4 版规范中记录：没有元素表、没有示例，附录仅涵盖 SRU 和 OAI-PMH。更糟的是，规范指出格式错误的参数返回零结果响应而非错误——「引数（パラメータ）誤りの場合には検索結果ゼロ件となる」——因此字段名中的拼写错误与真正的不存在无法区分。对于一个目的是让历史学家相信"什么都没找到"的工具来说，这是不合格的。SRU 返回类型化诊断和文档化的 DC-NDL 记录模式。以后添加 OpenSearch 不需要新的通知；它需要的是文档化的响应格式。

来源

• 国立国会図書館サーチ 外部提供インタフェース仕様書 第1.4版（2026-03-31）

• APIのご利用について——条款、署名要求、并发、通知

• API提供対象データプロバイダ一覧——dpid 值和许可条件

许可证

MIT。通过本服务器检索的元数据来自国立国会图书馆，采用 CC BY 4.0 许可；服务器发出的署名行是该许可要求的署名，应保留在你从结果中发布的任何内容中。

已测试和未测试的内容

已于 2026 年 8 月 19 日针对在线 API 验证：

• 在蔵書和雑誌記事索引中日文假名搜索——总数正确、记录正确、年份和标识符正确。

• DC-NDL 解析，包括表现形态存根过滤器。NDL 每条记录返回两个 BibResource 元素；在过滤器加入之前，同时取两者会使结果集翻倍并出现空白。

• searched_for 报告的是所选检索词而非组装后的 CQL，因此其脚本检测是有意义的；确切的 CQL 在 query.params 中，并由收据哈希固定。

• DPID_NOT_PERMITTED 防护：指定 ndl-dl 的请求在进程内被拒绝。

• RESERVED_WORD_IN_QUERY：War AND Peace 被拦截，War and Peace 通过。

• 速率限制器，非自愿地——见上文 HTTP 429。

未针对在线 API 验证，而是阅读而非运行： "记录不存在"透传、ndl_get_record 和退避路径。测试在 429 处停止而非继续，因为通过探测来刻画未公开的速率限制正是条款所警告的継続して大量のアクセス，而本服务器的意义恰恰在于不成为国立国会图书馆不得不封锁的对象。在正常使用中逐条查询地练习这些路径。