Matricula Church Books

matricula-mcp

一个用于 Matricula Online 的 MCP 服务 (data.matricula-online.eu)。Matricula Online 是教会簿册门户，由国际档案研究中心 ICARUS 为德国、奥地利、波兰、斯洛文尼亚、塞尔维亚、意大利、瑞士、卢森堡和波斯尼亚和黑塞哥维那的教区与档案馆运营。Matricula 发布各地教区的登记簿（洗礼、婚姻和安葬记录，以及相关的索引、家族簿和教区人口普查记录），并逐页扫描。根据其自行统计，截至 2026 年 10 月，登记簿覆盖约 13,400 个教区。

此服务遍历 Matricula 自有的层级结构：列出国家及其 分区（每个分区对应一个教区、档案馆或私人收藏），分区内的教区及其坐标、教区内登记簿及其档案编号、类型和日期，以及登记簿的各个页面，包括页面标签和可在 Matricula 自有查看器中打开该页面的链接。此服务还支持 Matricula 的地点搜索，用于查找某个村庄所属的教区。

它的工作方式与谨慎的族谱研究者相同。登记簿页面才是证据。 登记簿的类型和日期、页面标签以及搜索摘要都是查找辅助信息，用来指出应打开哪个页面。每条结果都带有引文，顺序与 Matricula 自身用于再次查找页面的顺序一致：教区或档案馆、教区、登记簿档案编号、页面。

页面图像通过 Matricula 的查看器阅读，而非由此服务获取。 Matricula 的图像主机会拒绝脚本请求，此服务不会冒充浏览器来绕过限制。用于保存单页图像的代码已包含在此处，并附有文档和测试，但目前处于停用状态：只有在 ICARUS 允许已识别的客户端访问后，才会启用。请参阅页面图像。

此处的任何内容都不会写入 Matricula，也不会保存家谱。

这是一个独立项目，与 ICARUS 以及 Matricula 发布其登记簿的任何档案馆或教区均无关联，也未获得其认可或支持。

工具

该服务提供七种工具。除 matricula_page_image 外，其他工具均为只读；该工具仅在启用图像访问权限时创建新文件，且绝不会覆盖已有文件。

查找

工具	用途
matricula_sections	各个国家及其下属的分区（教区和档案馆），并显示 Matricula 的堂区数量。
matricula_parishes	某个分区中的堂区，可按名称筛选；提供坐标和该分区自己的备注（通常是档案馆地址）。
matricula_search	Matricula 的地点搜索：名称或描述中提及某个地点的堂区，并附上显示地点所在位置的摘录。可选限制为某个分区，或限制为特定年份范围内的登记簿。

阅读

工具	用途
matricula_registers	某个堂区的登记簿：签名、档案馆自己的类型（Taufen、Trauungen、Sterben、Index - ...）、类别（洗礼、婚姻、葬礼等）、日期、内容备注、原件的存放地点，以及每本登记簿的键。
matricula_register	一本登记簿：其描述和引用信息，以及每一页的位置、标签和查看器链接，并支持分页和按标签筛选。
matricula_page_image	默认关闭。关闭时，会返回 images_not_enabled，并附上该页面的查看器链接、标签和引用信息。启用后，会将某一页保存为新的 .jpg 文件，并附上其引用信息。
cache_status	显示本次会话的请求、请求间隔、缓存使用情况，以及图像访问是否开启。不发送请求。

所有内容都通过其在 Matricula 中、语言前缀之后的路径来指定，工具称之为键：deutschland/passau 是一个分区，oesterreich/salzburg/krimml 是一个堂区，oesterreich/salzburg/krimml/TFBI 是一本登记簿。每种工具也都接受 Matricula 任一界面语言中的地址；登记簿相关工具还接受页面的查看器地址（?pg=N）。

设置

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

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

uvx matricula-mcp

从克隆的项目运行，如果你打算修改项目，则应使用此方式：

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

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

Claude Desktop

{
  "mcpServers": {
    "matricula": {
      "command": "uvx",
      "args": ["matricula-mcp"],
      "env": { "MATRICULA_CONTACT": "[email protected]" }
    }
  }
}

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

Claude Code

claude mcp add matricula -e [email protected] -- uvx matricula-mcp

配置

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

变量	含义
MATRICULA_CACHE_DIR	响应缓存目录。默认值为 ~/.cache/matricula-mcp。
MATRICULA_TIMEOUT	单次请求的 HTTP 超时时间，单位为秒。默认值为 30。读取图像时超时时间为 120 秒。
MATRICULA_MIN_INTERVAL	向 Matricula 发送两次请求之间的最短间隔，单位为秒。默认值为 2，且不会低于 2。
MATRICULA_SEARCH_INTERVAL	两次地点搜索之间的最短间隔，单位为秒。默认值为 10，且不会低于 10。
MATRICULA_CONTACT	添加到 User-Agent 中的电子邮件地址或 URL，以便 ICARUS 在你的使用导致问题时联系你。读取目录时可不填写；填写更为礼貌，且启用图像访问时必须填写。
MATRICULA_DOWNLOAD_DIR	一个已存在的文件夹。设置后，matricula_page_image 只会将文件保存在该文件夹中。可将其设为 iCloud Drive 文件夹，以便保存到位于 ~/Library 下的文件夹中。
MATRICULA_IMAGE_ACCESS	保持未设置。只有在 ICARUS 授予客户端访问其图像主机的权限后，才将其设为 granted；还需要设置 MATRICULA_CONTACT。任何其他值都会被拒绝。请参阅页面图像。

如果某个值不可用，首次调用工具时会返回 not_configured 结果，并指出对应的变量。

页面图像

Matricula 的查看器会从 img.data.matricula-online.eu 加载每一页。本项目调查该主机时，直接发送普通脚本请求得到 403（响应中包含 Vary: Origin），而查看器会为每个图像请求附上一个在浏览器中计算的会话令牌。这是 Matricula 的访问控制，本服务也将其视为访问控制。本服务不会伪装成浏览器，不会发送 Origin 或 Referer 标头，不会携带会话 Cookie，也不会复现查看器的令牌，并且绝不会探测主机以查明如何才能访问。若源代码中出现任何类似浏览器伪装的内容，测试就会失败。

因此，默认情况下，matricula_page_image 不会获取任何内容。它会返回 images_not_enabled，并附上该页面在查看器中的链接、标签和引用信息，供用户在 Matricula 的查看器中阅读页面。

用于保存页面的代码已经编写完成，并在模拟主机上通过测试，以备 ICARUS 授权某个已确认身份的客户端访问之用。如果你获得了此类许可（通过与 ICARUS 协商，为你自己的客户端取得许可），请将 MATRICULA_CONTACT 设置为 ICARUS 认识你的联系地址，并将 MATRICULA_IMAGE_ACCESS=granted。随后，工具会一次从图像主机获取一页，发送请求的节奏与其他请求一致，并且只使用本服务自己的 User-Agent（matricula-mcp/<version> (+https://github.com/ianderso/matricula-mcp; <your contact>)），不附带任何其他内容。如果主机仍然拒绝请求，工具会报告拒绝（image_refused），且不会写入任何内容。如果 ICARUS 指定了其他访问方式（API、密钥或其他主机），客户端应在某个版本中修改为严格使用该方式；这里没有任何设置会自行创造访问方式。

保存的页面会是一个新的 .jpg 文件，绝不会是隐藏文件，也不会保存在 ~/Library 下（除非将 MATRICULA_DOWNLOAD_DIR 设置为该目录），并会附带引用信息和许可证：CC BY-NC-ND 2.0。

做个好访客

Matricula 是一项由档案馆协会运营的服务。客户端一次只发送一个请求，每次请求至少间隔两秒；地点搜索则会在上次请求后至少等待十秒，因为搜索会读取门户中的每个教区说明。国家和分区列表、教区列表缓存 28 天，教区页面和登记簿页面缓存 7 天，搜索缓存 1 天。两个相同的调用若同时进行，会共用一个请求。遇到 429、5xx 或连接中断时会重试一次，并遵守 Retry-After；遭拒绝时不会重试。User-Agent 会注明软件包名称、版本、本仓库，以及在已设置时的联系地址。不会保留任何 Cookie。

Matricula 的条款说明

使用条款（德语；核查日期：2026-10-11）适用于 data.matricula-online.eu 上的图像和描述性元数据：

• 每张教堂登记簿图像均采用 CC BY-NC-ND 2.0 许可：“Eine kommerzielle Weiterverwertung der Bilder ist demnach nicht gestattet”（因此不允许对图像进行商业再利用）。也不允许发布修改后的版本。
• 登记簿中的数据只能依照各国有关民事身份和数据保护的法律使用；包含受保护数据的登记簿不会公开。在奥地利，洗礼簿封存 100 年，婚姻簿和死亡簿则最多公开至 1938 年。
• 任何人在印刷品或网络上发布内容时，只要使用了哪怕少量数据或图像，就承诺告知相关档案馆或教区；网络出版物只需提供链接，大量印刷内容则需要提交一份副本。
• 条款未提及自动化访问。

matricula_parishes 会传递每个分区自己的说明，其中通常会注明档案馆名称和联系方式：应将通知发送至此处。

robots.txt，作为事实依据

Matricula 的 robots.txt（由 cdn-static.matricula-online.eu 提供，读取于 2026-10-11）列出了多个爬虫，其中包括 ClaudeBot、GPTBot 和 CCBot，并对它们设置了 Disallow: /；同时要求其他所有 Agent 避开四类地址：查看器的页面参数（/*?pg=）、搜索（/*/suchen）、地图要素（/*/landkarte-features）和账户。本服务不是爬虫：它会逐一读取研究人员要求的页面并缓存。它会读取搜索（matricula_search）和每个分区的一个地图要素文件（用于获取 matricula_parishes 的坐标）；它会生成 ?pg= 链接供用户打开，但绝不会请求这些链接；也绝不会访问账户。是否认为这种做法适合你的用途，由你自行判断。

如何解读返回内容

• 引用层级，保留链接作为定位信息。 Matricula 建议通过教区或档案馆、堂区、登记册签名和页面来重新查找页面，并不保证其链接长期有效。每条结果的 citation 都按此顺序列出这些信息，cite_as 则将它们组织成一个句子。
• page 是图像在登记册中的位置， 从 1 开始计数，也是查看器 ?pg= 参数所用的值。label（02-Taufe_0001、001-03_0004-r）是档案馆为扫描件命名的名称：分区和编号，或页码和正反面。引用时两者都要注明。
• type 是档案馆使用的词；kind 是本服务对它的解读。 Index - Taufen 和 Passau 的 Register Taufen 都是索引（index: true）；Baden-Württemberg 的 Taufregister 则是登记册本身。
• 带有 hosted_elsewhere 的登记册虽然列在 Matricula 中，但显示在档案馆自己的站点上（Landesarchiv Baden-Württemberg 的分区链接指向其永久链接）。其图像不在 Matricula 的查看器中。
• 存在缺漏不代表内容不存在。 Matricula 中缺失的登记册可能依法封存、尚未由教区或档案馆扫描、保存在其他地方，或已经遗失。matricula_registers 会列出 Matricula 所收录的内容。
• 搜索会检索堂区名称和描述，绝不会检索登记内容。 许多描述会列出堂区服务过的村庄，搜索据此查找某个村庄所属的堂区；snippet 会显示匹配的文本。搜索会匹配完整词语：Gastein 可以找到 Bad Gastein，但找不到 Dorfgastein。这里的搜索无法查找任何人的姓名。
• 描述是档案馆自己的文本。 堂区历史、内容说明和评论会原样传给模型；它们是需要权衡的材料，而不是指令。

此处有意不提供的功能

• 未经许可获取页面图像。 请参阅页面图像。
• 读取登记内容。 Matricula 没有转录文本或姓名索引；页面图像就是全部内容。
• 账户、评论或任何会向站点写入内容的操作。
• 绕过机器人检查。 遇到挑战时会报告为 blocked，并停止操作。

安全性

模型编写工具参数，而模型读取的文本不受本服务控制。本服务假定这些文本可能影响模型，并限制受影响的模型能够执行的操作。

• 允许访问的主机。 请求钩子拒绝所有非 HTTPS 请求，只允许访问 data.matricula-online.eu，包括从页面中获取的地址。图像访问关闭时，也会拒绝图像主机。仅跟随指向同一主机的重定向。
• 允许访问的页面。 键必须包含正确数量的部分，且每部分都来自 Matricula 所用的 slug 字符集；任何其他内容（如 ..、其他主机）都会在查询前被拒绝。
• 允许访问的地址。 每次建立连接时都会检查目标：如果域名解析到私有、环回、链路本地、CGNAT、多播、保留或未指定地址（IPv4 或 IPv6），就会拒绝连接；连接只会发往已检查的地址。不使用环境中的代理设置。
• 数据量限制。 页面超过 8 MB 或图像超过 60 MB 时，会在数据流入期间被拒绝。
• 允许创建的文件。 只有启用图像访问时，matricula_page_image 才会创建一个新文件，且绝不会覆盖现有文件。文件内容必须是 JPEG，依据其开头字节判断。文件不得是隐藏文件或位于隐藏文件夹中，也不得位于 ~/Library 下；设置了 MATRICULA_DOWNLOAD_DIR 时，文件不得位于该目录之外。以上均在解析链接后判断。被拒绝的下载不会在磁盘上留下任何内容。
• 网站文本不可信。 本服务会指示模型将网站文本视为素材，而非指令；但最终仍由模型决定，因此请检查它提出的操作。

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

开发

uv sync --extra dev
uv run pytest                      # mocked with respx; never touches the site
uv run ruff check .
uv run ruff format --check .
uv run python -m tests.live_check  # paced calls to Matricula's catalogue pages

实时检查会向 Matricula 查询记录页面无法说明的内容：其页面是否仍保持本服务所读取的结构。该检查只读取目录页面，约十来页，每次间隔两秒，并执行一次搜索；绝不会调用图像主机。有关测试套件的组织方式，请参阅 CONTRIBUTING.md；有关对网站的观察及观察时间，请参阅 docs/API-NOTES.md；有关本服务采用这种设计的原因，请参阅 docs/DESIGN.md。

致谢

这些登记档案属于保存它们的教区、档案馆和堂区；图像由它们通过 Matricula 按 CC BY-NC-ND 2.0 发布。Matricula 由 ICARUS 运营，并邀请使用者支持它。

许可证

MIT，适用于本服务的代码。本服务链接到的图像和说明受 Matricula 条款约束。