CONTENTdm State Archives

contentdm-mcp

一个面向美国州档案馆和州立图书馆在 CONTENTdm 上发布的记录图像的 MCP 服务：死亡证明及其年度索引、邦联养老金档案、选民登记簿、监狱登记簿、县法院和遗产文件、信件和日记，以及机构添加的文字转录或 OCR 文本。

CONTENTdm 是 OCLC 托管的数字馆藏平台。阿拉巴马州档案与历史部、佐治亚州档案馆的 Virtual Vault、田纳西州立图书馆与档案馆、Ohio Memory、伊利诺伊州数字档案馆、印第安纳州立图书馆、密苏里数字遗产等众多机构都使用它，而且每个机构都提供相同的免密钥 JSON API 和 IIIF 图像服务。本服务附带一份精选站点列表，可同时搜索其中一个或多个站点、读取条目及其页面，并下载页面图像供阅读。

它的工作方式与谨慎的家谱研究者相同。**页面图像才是证据。**文字转录或 OCR 文本是指引你查阅哪个页面的线索，而索引卡则是查找背后记录的工具。每条结果都附带馆藏机构的条目地址和引文核心信息（机构、馆藏、标题、标识符、地址），因为引用时应引用条目页面，而不是本服务。

本服务不会写入任何位置，也不会保存家谱。它可以与 dpla-catalog-mcp 搭配使用，后者可在数百个馆藏中查找条目并提供机构地址（get_item 可直接接收该地址）；也可与用于联邦记录的 nara-catalog-mcp 搭配使用。

这是一个独立项目，与 OCLC 或本服务访问其站点的任何机构均无关联，也未获其认可或支持。

工具

本服务提供八个工具。除 get_image 外，其余均为只读；get_image 会写入一个新文件，且绝不会覆盖已有文件。

查找

工具	用途
list_instances	列出精选站点：各站点的运营方、对家谱研究者有用的馆藏、任何再利用条款，以及核查日期。已离开 CONTENTdm 的站点会注明迁移去向。不发送请求。
list_collections	列出某个站点的馆藏，以及搜索时使用的各个别名。
get_collection	获取单个馆藏的字段信息：search 可在 field 中指定的字段，以及存放文字转录或 OCR 文本的字段。
search	搜索一个站点，或并排搜索多个站点。说明哪些站点已响应、失败或超时，以明确负面结果的适用范围。page_hits 会返回卷册中出现文本匹配项的页面。

阅读

工具	用途
get_item	获取单个条目：元数据、文字转录或 OCR 文本、机构自带的“引用格式”行和权利声明，以及引文核心信息。若为页面，还会说明其所属对象和页码。可接收某个可访问站点上的条目地址，例如 DPLA 的 isShownAt。
get_pages	按顺序列出复合对象的页面，并通过 query 标记匹配的页面。
get_image	通过站点的 IIIF 服务下载一张页面图像，并调整尺寸以适配；也可下载多页 PDF 中的任意一页。保存为新的 .jpg，绝不会保存为隐藏文件或存放在 ~/Library 下。
cache_status	按站点显示本次会话的请求和缓存使用情况。不发送请求。

精选站点

list_instances 会返回完整列表。截至 2026-10-06，有 18 个站点响应，另有 7 条记录标明已退出 CONTENTdm 的机构，方便搜索时了解它们迁往何处：

州	站点	状态
AL	Alabama Department of Archives and History	支持
AK	Alaska's Digital Archives	支持
AR	Arkansas State Archives	支持
CT	Connecticut State Library	支持
DE	Delaware Division of Libraries, with the Delaware Public Archives	支持
GA	Georgia Archives, Virtual Vault	支持
IL	Illinois Digital Archives	支持
IN	Indiana State Library (Indiana Memory); Ball State University	支持
KY	Kentucky Digital Library	支持
MO	Missouri Digital Heritage	支持
ND	Digital Horizons	支持
NM	New Mexico Digital Collections, with the State Records Center and Archives	支持
NV	Nevada State Library, Archives and Public Records	支持
OH	Ohio Memory	支持
OK	Oklahoma Department of Libraries, with the Oklahoma State Archives	支持
TN	Tennessee State Library and Archives (TeVA)	支持
WA	Washington Rural Heritage	支持
AZ	Arizona Memory Project	已退出 CONTENTdm；受到机器人检查拦截
ID, SD	State archives' digital collections	已迁移至 Preservica
MT	Montana Memory Project	已迁移至 Recollect
NC	State Archives of North Carolina	已迁移至 Quartex
PA	POWER Library	已迁移至 Islandora
WI	Wisconsin Historical Society	已迁移至自有站点

其他 CONTENTdm 站点也可以使用，只需访问其 cdmNNNNN.contentdm.oclc.org 地址，并将 https://cdmNNNNN.contentdm.oclc.org 作为 instance 传入。无论经典站点各自使用什么域名，都可以通过该地址访问；其页面源代码会注明编号（"cdmServerUrl": "serverNNNNN.contentdm.oclc.org"）。 此类站点超过 675 个，而且没有注册表。若要通过站点自己的域名使用，请将其添加到 CONTENTDM_EXTRA_INSTANCES；出于安全性一节中的原因，工具参数无法实现这一点。

设置

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

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

uvx contentdm-mcp

从克隆的仓库运行，适用于你打算修改代码的情况：

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

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

Claude Desktop

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

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

Claude Code

claude mcp add contentdm -- uvx contentdm-mcp

配置

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

变量	含义
CONTENTDM_CACHE_DIR	响应缓存目录。默认值为 ~/.cache/contentdm-mcp。
CONTENTDM_TIMEOUT	单次请求的 HTTP 超时时间，单位为秒。默认值为 30。读取图像时超时时间为 120 秒。
CONTENTDM_MIN_INTERVAL	向同一站点发送两次请求之间的最短间隔秒数。默认值为 1，且不低于 0.5。
CONTENTDM_CONTACT	添加到 User-Agent 中的电子邮件地址或 URL，以便在你的使用造成问题时，机构能够联系你。可选，且出于礼貌建议填写。
CONTENTDM_EXTRA_INSTANCES	工具可通过各自域名访问的其他站点：以逗号分隔的 https 基础 URL，或一个 YAML 文件的绝对路径；文件条目格式参见 instances.yaml（仅需 base_url）。list_instances 会列出这些站点；搜索所有站点时不会包含它们。
CONTENTDM_DOWNLOAD_DIR	一个已存在的文件夹。设置后，get_image 只会在其中保存文件。可将其设为 iCloud Drive 文件夹，以便保存到 ~/Library 下的目录中。

无效的值会在首次调用工具时通过 not_configured 结果报告，并指出对应变量。

做个好访客

每个站点都是一个机构的服务。客户端一次只向每个站点发送一个请求，且请求间隔至少一秒；跨多个站点搜索时，会并行搜索，每次最多六个，因此每个站点同时最多只会收到一个调用。同一时间发出的两个相同调用会共用一个请求。馆藏列表和字段定义缓存 30 天，条目缓存 7 天，搜索缓存 1 天。遇到 429、5xx 或连接中断时，会遵循 Retry-After 重试一次。User-Agent 会标明软件包、版本和此代码仓库。

这些站点的 robots.txt 禁止访问网站的搜索页面，不禁止此服务使用的 API。各机构自己的条款决定你如何使用其图像：list_instances 和 get_item 会转达站点所述内容，且有几家机构要求在出版前获得许可。

如何解读返回结果

• 搜索范围仅限于 answered 中的站点。 failed、timed_out 和 not_searched 会列出未被否定结果覆盖的站点。发生重定向、要求进行机器人验证或未列出任何馆藏的站点通常已迁移。
• 搜索范围包括元数据和文本字段，不包括图像。 许多记录图像完全没有文本，因此某个名称可能出现在搜索无法找到的页面上。请改为按馆藏或索引卷浏览。
• 复合对象的文本位于其页面上。 卷、文件和报纸期号都是复合对象；它们自身的转录字段通常为空。使用 page_hits=true，或在 get_pages 中使用 query 查找页面。
• 字段名称因馆藏而异。 一个馆藏中的“父亲姓名”字段是 namea，另一个馆藏中则是 father。get_collection 会说明哪个字段名对应什么内容，以及哪个字段是转录字段：该字段按类型标记，因为不同站点的字段名各不相同。
• “转录”可能是机器 OCR。 田纳西州生命记录索引中标为转录的内容是 OCR 识别结果。请查看图像。
• exact 是短语搜索（词语须按顺序连续出现），而非整个字段完全相等。all 要求包含每个词，any 则只需包含其中一个。
• 一个 PDF 条目可能包含多页。 其 IIIF 图像显示第一页；使用带 pdf_page 的 get_image 可访问其他页面。
• page 是对象中的位置， 从 1 开始计数，并非扫描件上印刷的页码：阿尔文·C·约克军士的条目位于田纳西州 1960-1964 年死亡索引第 8 卷第 461 页，扫描件名称为 54784_460，印刷页码为 457。如果印刷页码不同，也请一并注明。
• 引用条目页面。 使用每个结果附带的 citation；如果 get_item 找到机构自己的 cite_as 行，也请使用（佐治亚州、俄克拉何马州和阿拉斯加州的条目中包含此信息）。记录标识符（alias:pointer），以便之后再次找到该条目。

刻意不提供的功能

• 向任何网站写入内容。 CONTENTdm 的写入功能需要员工登录。
• 使用其他平台的网站。 新版 CONTENTdm（于 2026-09-22 发布）没有公开发布的 API，而 Quartex 的 API 未提供文档说明。工具通过适配层与其通信，因此可添加任一平台，而无需更改这些工具；请参阅 docs/DESIGN.md。
• 绕过机器人检查。 如果网站返回质询，系统会将其报告为受阻并停止访问。

安全性

工具参数由模型编写，而模型会读取此服务无法控制的文本：标题、转录文本、DPLA 记录和网页。此服务假设这些文本可能影响模型的行为，并限制受影响的模型能执行的操作。

• 允许访问的主机。 工具可访问精选网站、contentdm.oclc.org 下的任意地址（OCLC 自有服务器），以及你在 CONTENTDM_EXTRA_INSTANCES 中列出的网站。任何其他主机都会在查找之前遭到拒绝，因为仅查询 secret.attacker.example 的 DNS 就会暴露该名称；拒绝信息会说明如何访问该网站。
• 允许访问的地址。 每次建立连接时都会检查目标地址：如果某个名称指向私有、环回、链路本地、CGNAT、多播、保留或未指定地址（无论是 IPv4 还是 IPv6），连接都会遭到拒绝；实际连接的地址就是已检查的地址。重定向仅会在同一实例的主机之间进行，且会再次检查。不会使用环境中的代理设置。
• 数据量限制。 JSON 响应超过 10 MB，或图像超过 60 MB 时，会在流式传输过程中遭到拒绝。
• 允许使用的文件。 get_image 会创建一个新文件，绝不会覆盖现有文件。文件内容必须是图像（根据其开头字节判断，而非 Content-Type），且格式必须与文件扩展名一致：.jpg 或 .jpeg。文件不得是隐藏文件或位于隐藏文件夹中，不得位于 ~/Library 下；如果设置了 CONTENTDM_DOWNLOAD_DIR，文件也不得位于该目录之外。所有这些判断都会在解析链接后进行。下载遭到拒绝时，磁盘上不会留下任何内容。
• 参数会经过验证（包括集合别名、字段简称和数字指针），之后才会用于请求；搜索词中的 API 专用语法字符也会被去除。
• 网站文本不受信任。 标题、描述和转录文本会原样传递给模型。服务的指令要求模型将这些文本视为需要权衡的材料，而不是指令；但最终仍由模型作出决定，因此请检查它提议执行的操作。

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

开发

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

实时检查会询问网站，仅凭已记录的测试样本无法确认的事项：它们的响应是否仍符合此服务所读取的格式，以及每个精选网站是否仍能正常响应。有关测试套件的组织方式，请参阅 CONTRIBUTING.md；有关 API 的观察结果及其时间，请参阅 docs/API-NOTES.md；有关此服务为何采用这种设计，请参阅 docs/DESIGN.md。

致谢

图像和描述的版权归发布它们的机构所有。CONTENTdm 是 OCLC 的产品。

许可证

MIT。