SNAC Archives

snac-archives-mcp

一个用于查找哪些档案馆收藏着相关文献的 MCP 服务：家族的信件、教会的登记簿、商店的账簿、县政府办公室的散存文件。这些资料大多从未数字化。它们只以目录记录或检索工具的形式在线上某家图书馆中存在；研究的难点在于找到正确的馆藏。

该服务搜索 SNAC Cooperative 的人物、家族、组织及收藏其文献的档案馆藏索引，涵盖数千家存储机构。数据采用 CC0 许可，API 无需密钥或账户。它还会为你生成可打开的 ArchiveGrid 搜索；因为 ArchiveGrid 往往能找到 SNAC 找不到的内容，而 OCLC 不允许自动访问。

它的工作方式就像一位谨慎的家谱研究者。它返回的所有内容都是检索工具：只能说明去哪里查、那里大致有什么，不能证明文献写了什么。这些工具会明确说明这一点，并引导你查看馆藏机构自己的检索工具；引用时应以该工具中的描述为准。

这里的任何操作都不会写入数据，也不会保存家谱树。该服务负责查找馆藏；你从文献中得出的结论应记录在你的家谱软件中，或记录在与之并行运行的家谱树 MCP 服务中。它也适合与 nara-catalog-mcp（联邦记录）和 familysearch-mcp（已编目的记录和图像）搭配使用。

这是一个独立项目，与 SNAC Cooperative、弗吉尼亚大学或 OCLC 均无关联，也未获其认可或支持。

工具

该服务提供八个工具，全部为只读，并附有客户端注释。其中两个完全不会发起网络请求。

查找馆藏

工具	用途
search_collections	根据标题中的词语查找馆藏。每条结果都会列出馆藏机构的邮寄地址、OCLC 编号和链接，并标记可能的重复项（同一批文献被编目两三次）。
get_collection	获取单个馆藏的完整信息：完整摘要、范围、馆藏机构、链接，以及 SNAC 关联到该馆藏的名称。
repository_holdings	查看 SNAC 关联到某家馆藏机构的内容，可按标题筛选并分页。

查找人物、家族和组织

工具	用途
search_names	按名称查找 SNAC 名称记录，可选择按类别筛选：个人、家族或法人团体（教会、企业、社团、办公室）。
get_name	获取单条名称记录：标题、日期、地点、生平说明和标识符链接（VIAF、美国国会图书馆等）。指定 detail="full" 时，还会返回与其关联的所有馆藏及其关联角色，以及相关名称。
collections_in_common	查找与两个名称都关联的馆藏：了解哪里可能保存着联姻家族之间的信件或祖先的关联人士的资料。

SNAC 的边界

工具	用途
archivegrid_search_link	按字段语法生成 ArchiveGrid 搜索链接供你打开；也可根据 OCLC 编号生成记录链接。不发起请求。
cache_status	查看本次会话的实时调用和缓存命中情况。不发起请求。

设置

你需要 Python 3.11 或更高版本以及 uv。无需申请密钥。

无需克隆。 uvx 会从 PyPI 获取并一步运行：

uvx snac-archives-mcp

从克隆的仓库运行，如果你打算修改项目，就应选择这种方式：

git clone https://github.com/ianderso/snac-archives-mcp
cd snac-archives-mcp
uv sync
uv run snac-archives-mcp   # stdio server, usually launched by the client

无论采用哪种方式，该服务都通过标准输入/输出使用 MCP，因此通常应让 MCP 客户端启动它，而不是手动运行。

Claude Desktop

{
  "mcpServers": {
    "snac": {
      "command": "uvx",
      "args": ["snac-archives-mcp"]
    }
  }
}

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

Claude Code

claude mcp add snac -- uvx snac-archives-mcp

配置

无需进行任何配置。服务器启动目录中的 .env 文件可提供环境中未设置的值；只会读取该目录中的文件。

变量	含义
SNAC_API_URL	SNAC REST 端点。默认值为 https://api.snaccooperative.org/。必须使用 https；服务器只会联系该主机。
SNAC_CACHE_DIR	响应缓存目录。默认值为 ~/.cache/snac-archives-mcp。
SNAC_TIMEOUT	HTTP 超时秒数。默认值为 60。馆藏列表的超时为 120。
SNAC_CONTACT	添加到 User-Agent 中的电子邮件地址或 URL，以便在你的使用造成问题时，SNAC 团队能够联系你。可选，建议填写。

无法使用的值会在首次调用工具时报告为 not_configured 结果，并注明变量名称。

做个友好的使用者

SNAC 是由一个小型合作组织运营的免费服务，且没有公布速率限制。服务每次只发送一个请求，且请求间隔至少一秒；两个同时进行的相同调用会共用一个请求；每个答案都会在磁盘上缓存 30 天（馆藏记录的缓存时间很充足）。遇到 429 或 5xx 错误时会进行三次重试，每次增加等待时间，之后报告为 rate_limited 或 upstream_error，绝不会将其误报为“未找到任何内容”。传入 refresh=true 可重新查询；在断定某项内容不存在之前，请刷新缓存中的空结果。

如何解读返回结果

• 检索工具不是档案本身。 馆藏描述说明这些档案存在，并大致介绍其中的内容。不要仅凭描述就为某个事实添加引用；应将其记录为研究任务（申请副本、计划到访）。
• **引用档案馆自己的检索工具，**注明档案馆和馆藏编号，例如“Wilder and Anderson Family Papers #01255, Southern Historical Collection, Wilson Library, UNC-Chapel Hill”。不要引用 SNAC 或 ArchiveGrid：它们只是索引。如果 link_kind 是 finding_aid，链接会指向该检索工具；否则请在档案馆自己的目录中查找该馆藏。
• 记录标识符。 OCLC 编号可将同一馆藏在 WorldCat、ArchiveGrid 和 SNAC 中关联起来；SNAC ARK（ark:/99166/...）是名称记录的稳定 ID。也要记录档案馆的馆藏编号：WorldCat 会合并记录，而且编号对应的页面可能会重定向到其他内容。
• **描述详略差异很大，**有的只是单行目录记录（“Papers, 1881-1958”，4 箱），有的则细到文件夹级别的清单。描述简略并不代表档案中没有某个人的相关资料。
• 标题搜索只搜索标题。 search_collections 要求馆藏标题中包含所有搜索词。“Davenport family papers”能找到 10 个馆藏；“Davenport family papers Lincoln County”则找不到，因为县名只出现在摘要中。请使用 search_names，或使用带有 place 的 ArchiveGrid 链接。
• 重复记录很常见。 一个馆藏通常既有 WorldCat 记录，也有一到两份采集来的检索工具，有时档案馆名称的写法也不同。possible_duplicate_of 会按标题词和年份将它们归组；这只是提示，并不表示记录已合并。
• 名称记录不等于身份确认。 SNAC 中有数百条标题为“Anderson family.”的记录，除了关联的馆藏外，没有其他信息可用于区分它们。在某个名称的馆藏中，creatorOf 表示这些是该名称所指对象本人的档案；referencedIn 表示该名称只是馆藏的索引词，并不意味着任何文献都与此人有关。上方的 maybe_same_count 大于 0，表示 SNAC 怀疑存在身份混淆。
• 奴隶主家族的档案是追寻被奴役祖先的主要途径。 许多描述只将被奴役者作为一个类别提及。请搜索奴役他们的家族档案，而不只是搜索祖先的姓名。
• 目录信息会过时。 SNAC 的馆藏索引主要基于 2010 年代的数据提取构建。馆藏会重新处理、重新编号和转移；州历史文献清查等调查中的“档案馆”记录的，也可能是数十年前调查时由镇书记员或教会保管的资料。联系档案馆前，请确认当前的索书号。
• ArchiveGrid 的索引存在局限。 location 指档案馆所在地；place 指档案所涉及的地点。其名称、地点和主题索引仅涵盖目录记录和 EAD 检索工具；HTML 和 PDF 检索工具只按关键词匹配。它会遗漏由多个图书馆共同保管的记录，因此通常找不到县级或教会记录的缩微胶片：这类资料请使用 WorldCat 或 FamilySearch Catalog。

刻意不提供的功能

• 向 SNAC 写入。 其编辑命令需要账户和 API 密钥。客户端拒绝发送除六条只读命令之外的任何命令，因此无论传入什么参数，都无法让它编辑任何内容。
• 获取 ArchiveGrid 内容。 OCLC 的使用条款禁止机器人和自动化复制，且该网站会屏蔽自动化客户端。服务端会生成地址，由用户自行打开。
• 从档案馆自有网站获取检索工具。 这会使服务端从一个 API 扩展到数千个主机，并需要为每个主机编写解析器，还会大幅扩大被注入文本影响的范围。以后可能会通过一个选项提供此功能。

安全

• 单一主机。 请求钩子会拒绝任何发往非配置 API 主机的请求，因此模型传入的值无法让服务器抓取其他站点。SNAC_API_URL 必须使用 https。
• 标识符经过验证（数字 ID 必须是 ASCII 数字，ARK 必须符合 SNAC 的模式），然后才会用于请求。
• 目录文本不可信。 摘要和人物简介由编目员和贡献者撰写，并会原样传递给模型。服务器的指令要求模型将这些文本视为需要权衡的材料，而不是指令；但最终仍由模型决定，因此请检查它提出的操作。

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

开发

uv sync --extra dev
uv run pytest                      # mocked with respx; never touches SNAC
uv run ruff check .
uv run ruff format --check .
uv run python -m tests.live_check  # eight paced calls to the live API

实时检查会向 SNAC 查询录制的测试数据无法验证的内容：其答复是否仍符合服务器读取的格式。有关测试套件的组织方式，请参阅 CONTRIBUTING.md；有关 API 的观察结果及时间，请参阅 docs/API-NOTES.md；有关服务器采用这种设计的原因，请参阅 docs/DESIGN.md。

致谢

数据属于 SNAC Cooperative，以 CC0 许可发布；其中的馆藏记录由其成员机构贡献，并取自 WorldCat 和查找工具。ArchiveGrid 是 OCLC Research 的一个项目。

许可证

MIT。