NARA Catalog

nara-catalog-mcp

一个用于在美国国家档案馆目录中进行家谱研究的 MCP 服务。查找祖先的抚恤金档案、服役记录或人口普查页面，阅读机器和志愿者转录的内容，并获取你将引用的页面图像。它还会搜索 NARA 的 Access to Archival Databases（AAD），这是目录无法访问的数据库：包括 NUMIDENT 中的社会保障申请和死亡记录、二战陆军入伍卡，以及 1820–1912 年的船舶乘客名单。

它的工作方式与谨慎的家谱研究者相同。目录描述是查找辅助工具，而 OCR 文本、转录内容和标签只是他人对页面的解读：它们都只是线索。页面图像才是来源。这些工具会明确说明各自的性质，服务还会提示模型在引用前先阅读图像。

这里没有任何功能会向目录写入内容，也不会保存家谱。该服务负责查找和阅读记录；你从中得出的结论应保存在家谱软件中，或保存在与本服务一起运行的家谱 MCP 服务中。

这些工具适用于目录中描述的任何记录，因此历史学家或记者也可以使用。本文中的示例都围绕追踪个人展开。

这是一个独立项目，与国家档案和记录管理局无关，也未获得其认可或支持。

工具

该服务提供 21 个工具。20 个工具仅供读取，并标记为客户端只读。另一个工具 download_page_image 会向本地磁盘写入新文件；它绝不会覆盖已有文件。

查找记录

工具	用途
search_records	按标题或全文搜索。返回总数以及简洁摘要：NAID、层级、馆藏单位、日期范围、图像数量。每个系列都会列出其创建者及制作该系列的办公室，以便区分多个同名系列。
search_records_advanced	同样的搜索，并提供用于缩小常见姓名搜索范围的筛选条件：日期范围、记录组、馆藏、祖先 NAID、描述级别、缩微胶片出版物编号、本地标识符、任意控制编号、国会届次、参考单位、创建者、个人或组织、地点、材料类型、反复出现的日期、仅数字化记录、“有转录内容／标签／评论”、精确匹配标识符、使用 search_after 游标翻阅超过 10,000 条的搜索结果，以及按需合并每条结果的 OCR 文本（来自 NARA 及其合作伙伴）。
browse_children	查看节点的直接子项：记录组到系列、系列到文件单元、文件单元到单件。沿着你信任的系列逐级向下查找。

阅读记录

工具	用途
get_record	按 NAID 完整读取一条记录：内容范围说明、层级、参考单位，以及包含对象 ID 的每一张页面图像。
get_record_images	按页面顺序列出页面图像，并提供每张图像的对象 ID 和 URL——这是引用前应阅读的证据。
download_page_image	按页码或 OCR／转录条目中列出的对象 ID，将一页保存为新的本地文件。媒体主机开放访问，因此不会消耗 API 配额。
get_online_availability	查看该记录还发布在哪些线上平台，包括商业合作伙伴的平台。
get_partner_digital_objects	查看商业合作伙伴（包括 Ancestry）与此 NAID 匹配的数字对象 ID。通常返回空列表。

机器和其他人对记录的解读

此组中的所有内容都是他人对文档的解读。它会告诉你要打开哪一页，但不会告诉你页面上写了什么。

工具	用途
get_extracted_text	按数字对象提取的页面图像 OCR 文本，包含提取者、对象总数，以及文件内容超出一次调用时的下一页结果。
get_transcriptions	公民转录内容——查看 OCR 无法识别的手写养老金档案的方式。
get_tags	公民标签，在家谱记录中通常是档案内人物的姓名。
get_comments	其他研究者对记录的备注。

搜索文档，而非目录

工具	用途
search_by_contribution_text	搜索转录内容、标签、备注和 OCR 文本，并返回完整的记录摘要。
search_transcriptions	查找转录文本中提及某个姓名或短语的记录。
search_tags	按精确标签或关键词查找带有相应标签的记录。
search_extracted_text	查找合作贡献的提取文本与查询匹配的记录。
search_comments	查找其他研究者发表过评论的记录。

NARA 的档案数据库访问（AAD）

AAD 将 NARA 的部分电子记录以可搜索表格的形式提供。 每一行都是机构职员根据记录录入的数据库条目：即转录内容或索引条目，而非记录本身；引用时应标注为电子记录。这些工具无需密钥，也不会占用目录 API 调用额度。

工具	用途
aad_list_series	AAD 类别中的系列（默认是家谱），每个系列都包含其文件及对应 ID。搜索仅针对单个文件。
aad_search	在单个文件中搜索整行自由文本和指定字段；每页 50 行，每行附带其记录 ID。
aad_get_record	完整的一行内容，包括每个编码值及其含义，以及按 NARA 推荐格式生成、注明检索日期的引用。

维护

工具	用途
api_budget	本次会话中的实时调用和缓存命中次数、缓存旁账本记录的本月实时调用次数，以及密钥每月调用额度的剩余量。

设置

你需要 Python 3.11 或更高版本、uv 和目录 API 密钥。请通过API 文档联系目录 API 团队申请密钥；默认额度为每月 10,000 次调用。

有两种方式运行服务。

无需克隆。 uvx 会从 PyPI 获取并运行它，一步完成，并缓存结果：

NARA_API_KEY=your-key uvx nara-catalog-mcp

从克隆版本运行，如果你打算修改它，就应选择这种方式：

git clone https://github.com/ianderso/nara-catalog-mcp
cd nara-catalog-mcp
uv sync
cp .env.example .env      # then put your key in it
uv run nara-catalog-mcp   # stdio server, usually launched by the client

无论选择哪种方式，服务都通过 stdio 使用 MCP 通信，因此通常应让 MCP 客户端启动它，而不是手动运行。

Claude Desktop

无需克隆：

{
  "mcpServers": {
    "nara": {
      "command": "uvx",
      "args": ["nara-catalog-mcp"],
      "env": { "NARA_API_KEY": "your-key" }
    }
  }
}

从克隆版本运行（如果密钥已放在克隆目录的 .env 文件中，可省略 env 块）：

{
  "mcpServers": {
    "nara": {
      "command": "uv",
      "args": ["--directory", "/path/to/nara-catalog-mcp", "run", "nara-catalog-mcp"],
      "env": { "NARA_API_KEY": "your-key" }
    }
  }
}

桌面应用并不总是会继承 shell 的 PATH。如果服务因找不到 uv 或 uvx 而无法启动，请将 which uvx 输出的完整路径作为 command。

Claude Code

claude mcp add nara --env NARA_API_KEY=your-key -- uvx nara-catalog-mcp

或者，从密钥存放在 .env 文件中的克隆版本运行：

claude mcp add nara -- uv --directory /path/to/nara-catalog-mcp run nara-catalog-mcp

配置

所有设置都来自环境变量。服务启动目录中的 .env 文件会为环境中未设置的变量提供值；使用 uv --directory 时，该目录就是克隆目录。服务只会读取该目录，不会读取其父目录，也不会读取安装软件包的目录。

变量	含义
NARA_API_KEY	你的目录 API 密钥。目录工具必需；AAD 工具无需密钥。
NARA_CACHE_DIR	响应缓存目录。默认值为 ~/.cache/nara-catalog-mcp。
NARA_TIMEOUT	HTTP 超时秒数。默认值为 60。
NARA_MONTHLY_CALL_BUDGET	密钥允许的每月调用次数，由 api_budget 报告。默认值为 10000。

如果缺少密钥或密钥值不可用，首次调用工具时会返回 not_configured 结果，并指出相应变量。

调用预算

Catalog 密钥有月度限额，搜索大量姓名会比预期更快地耗尽额度。每个成功的响应都会缓存在磁盘上，并按端点和查询建立索引，因此重复调用不会花费额度。实时调用也会记录到账本 budget.json 中，文件位于缓存目录旁边，因此 api_budget 会报告本月跨会话的支出，以及本会话的实时调用和缓存命中。被拒绝的调用也算作实时调用，因为它已到达 API。账本仅记录一台机器和一个缓存目录；Catalog 自身的计数才是权威数据。

缓存永不过期。对 get_record、get_record_images、get_extracted_text、get_transcriptions、get_tags 或 get_comments 传入 refresh=true，即可从 Catalog 重新读取一条答案：这会消耗一次调用，并替换缓存副本。新的转录和标签会逐渐出现，而且原本只有纸质文件的内容可能会被数字化，因此缓存的“这里什么都没有”最值得刷新。删除 NARA_CACHE_DIR 仍然有效，也会重置本月的账本。

搜索超过前 10,000 条结果

超过 10,000 条结果后，page 将不再生效；常见姓氏的搜索就可能超过这个数量。达到此上限时，search_records_advanced 会报告 paging_note；你可以缩小搜索范围，或使用 search_after="*" 重新运行搜索，并跟进每个响应中的 next_search_after 值。

搜索的工作方式

title 匹配记录标题中的词语，是精确度最高的选项；案卷通常以人物姓名命名。query 会搜索完整描述，范围更广、噪声更多，只有标题搜索找不到结果时才值得尝试。

返回的是摘要，而不是完整记录。原始 Catalog 记录很大，其中大部分内容与你要做的判断无关；你要判断的是这条记录是否值得打开。

搜索 AAD

AAD 没有 API，因此 aad_* 会像浏览器一样读取并解析其网页。这决定了它们的工作方式：

• 一次处理一个文件。 一个大型系列会拆分成多个文件，而搜索只针对其中一个文件。NUMIDENT 会按条目类型（申请、索赔、死亡）和姓氏范围拆分，因此要先调用 aad_list_series。
• 按名称指定字段。 fields={"LAST NAME": "PRESLEY", "DATE OF BIRTH (YEAR)": "1930-1935"}。AAD 以代码形式存储的字段（例如州或国家）无法按名称搜索：请将其含义放入 query，它会匹配整行内容，包括代码含义。
• 有意放慢速度。 一次只发出一个请求，且请求间隔至少两秒；搜索通常需要两个请求，因为 AAD 首先会返回“Please Wait”页面。答案会缓存在 NARA_CACHE_DIR/aad 中，缓存有效期为七天；对 aad_get_record 设置 refresh=true 可重新获取一行。
• 记录 ID 并不稳定。 NARA 会重新加载文件，重新加载可能导致行号改变。请重新搜索，而不要复用旧 ID；引用一行时，应注明其字段、文件和系列。
• 一行并不等于原始记录。 该行是根据 SS-5、穿孔卡或舱单录入的，因此会存在相应的录入错误，而且没有任何文件包含所有人。NUMIDENT 只收录已核实死亡或 1908 年以前出生的人员；其死亡文件不包含由州上报的死亡记录。每条答案都会附带 AAD 对该文件的说明，NUMIDENT 的答案也会指出该文件未收录的内容。

备注

• 描述不是证据。 描述只是对文件的概述，并不能说明任何单独页面的内容。引用前请先查看图像。
• OCR 不是证据，转录文本也不是。 get_extracted_text 是机器对手写扫描件的识读结果；get_transcriptions 是一位志愿者未经审核的录入文本。两者都是找到相关页面最快的途径，但都不是来源。请打开图像并引用它。
• 记录 NAID。 这是稳定的标识符，可让人重新找到引用内容。
• 并非所有记录都已数字化。 image_count: 0 表示描述存在，但页面未在线提供——reference_units 字段会告诉你纸质档案由哪个档案馆保存。
• 开放不代表不受限制。 媒体主机无需密钥即可访问，NARA 的大多数馆藏属于公有领域，但并非全部如此：部分描述记录了使用限制。重新发布图像前请先确认。

有意不包含的功能

Catalog API 可以发布标签和评论，也可以提交转录文本。此服务不会这样做，默认情况下也不会：提交的内容会以配置密钥的所有者名义发布，而且这里没有任何功能可以撤回。

安全

• 密钥从环境变量中读取，仅作为 x-api-key 标头发送给 catalog.archives.gov，绝不会发送给媒体主机或 AAD。密钥不会写入响应缓存。
• AAD 客户端只访问一个主机。 请求钩子会拒绝除 aad.archives.gov 以外的所有主机，因此模型传入的任何内容都无法让它获取其他网站的内容。客户端标识为 Mozilla/5.0 (compatible; nara-catalog-mcp/<version>; +<this repository>)，这是 Googlebot 等爬虫使用的格式。测试时，AAD 的负载均衡器对纯 nara-catalog-mcp/<version> 格式返回了 403；请参阅 docs/API-NOTES.md。
• 用户提交的内容是不可信文本。 标签、评论和转录文本由公众成员撰写，并会原样传给模型，因此其中可能包含针对模型的指令。服务的指令会要求模型将这些文本视为需要权衡的材料，而绝不是指令；但最终仍由模型决定，因此请审核它提出的操作。
• download_page_image 会写入文件。 它会在服务用户有写入权限的任意位置创建新文件，并拒绝覆盖现有文件——因此，即使路径有误或遭到注入，也不会破坏任何内容。此工具被标注为非只读，因此客户端可以在每次调用前征求确认。

如需报告漏洞，请参阅 SECURITY.md。

开发

uv sync --extra dev
uv run pytest                # mocked with respx; no API key needed
uv run ruff check .
uv run ruff format --check .
uv run python -m tests.live_check   # needs a key: asks the Catalog what the mocks cannot

实时检查会向 Catalog 查询模拟数据无法提供的信息：两个文本标志会将文本放在哪里、服务不会发送哪些搜索参数，以及搜索摘要是否仍会注明每个系列的创建者。它还会询问 AAD 是否仍接受客户端，以及解析器是否仍能读取其页面。 修改任意一端后都请运行检查；如果存在差异，输出中会显示。

有关测试套件的组织方式以及更改应包含哪些内容，请参阅 CONTRIBUTING.md。

API 说明

已发布的 OpenAPI 规范存在一些具体且可重复的问题——required 标志有误、该使用 maxLength 的地方却使用了 maximum，以及分页游标有两种互相冲突的定义。经实时 Catalog 验证的修正见 docs/API-NOTES.md。有关服务为何采用当前设计、哪些内容经决定不在范围内，以及测试套件如何构建，请参阅 docs/DESIGN.md。

许可证

MIT。