Norway Archives

norway-archives-mcp

一个面向挪威家族史的 MCP 服务：国家档案馆的教会簿册、人口普查和移民名单及其扫描件，国家图书馆的书籍和报纸，以及当今的官方地名。

• Digitalarkivet 由 Nasjonalarkivet（挪威国家档案馆）运营，收藏了教区登记簿（ministerialbøker 和 klokkerbøker）、1801–1920 年的人口普查、移民记录、遗嘱认证记录等。部分内容已转录并可搜索；更多内容是扫描件，只能逐页阅读。该服务两者兼顾：搜索转录内容，将扫描簿册中的列表（洗礼、坚信礼、婚姻、葬礼、迁入和迁出）对应到图像编号，并下载带有永久 ID 的页面。
• Nasjonalbiblioteket（国家图书馆）已将几乎所有挪威书籍和报纸数字化，其中包括家谱学家常用的按农庄编写的地方史 bygdebøker。许多内容只能从挪威境内访问，但搜索仍会告诉你某个名字出现在哪一页。
• Kartverket 的地名登记簿提供农庄或小村庄如今的拼写、类型和坐标。

它的工作方式就像一位谨慎的家谱学家。扫描页面才是证据。 转录内容只是线索（大多数教会簿册转录内容由承包商为 Ancestry、MyHeritage 和 FamilySearch 键入），而搜索无结果也只说明搜索了已转录的内容。返回的每个页面都附有来源、档案参考信息、图像编号和永久链接，因此引用指向的是档案，而不是此服务。

此处的任何操作都不会写入你自己的磁盘以外的位置，也不会保存家谱。

工具

该服务发布了 13 个工具。除两个下载工具外，其他工具均为只读；下载工具各自创建一个新文件，且绝不会覆盖已有文件。

工具	功能
da_search_persons	按姓名、历史市镇、名册类型和年份搜索 Digitalarkivet 的转录记录。
da_get_record	读取一条记录：其中的字段、记录中提到的所有人、来源，以及其扫描页面的永久 ID。
da_search_sources	按地点、时期和名册查找来源，并显示哪些名册已扫描、哪些可供搜索。
da_get_source	描述一个来源并映射其扫描件：档案参考信息、图像数量，以及各名册的起始图像。
da_list_pages	按顺序列出某个来源的页面；可选从某个名册的起始页开始，并提供永久 ID 和链接。
da_download_page	下载一张扫描页面（教会簿、人口普查，或任何带页面 ID 的内容），并附上引用信息。
nb_search	搜索国家图书馆的图书、报纸、期刊、地图等。
nb_search_inside	查找某个条目中提及某个词的页面，并提供片段和印刷页码。
nb_get_page	读取某个条目的一页：该条目开放时的 OCR 文本，以及引用信息。
nb_download_page	下载一张当前可访问条目的页面图像。
place_names	搜索 Kartverket 的官方地名登记册（农场、村落、湖泊、山脉）。
municipalities	查询 Digitalarkivet 的历史市镇及其编号，以及名册类型代码。无需网络。
cache_status	查看本会话的请求、Digitalarkivet 的每日额度和缓存使用情况。无需网络。

未转录名册（例如坚信礼名册）的一般操作流程：

1. da_search_sources(municipality="Røros", list_type="kf") 可查找包含坚信礼记录的教会簿，并指出坚信礼记录已扫描但不可搜索。
2. da_get_source(source_id=6540) 会提供坚信礼记录的起始图像。
3. da_list_pages(source_id=6540, section="kf") 会列出这些页面及其永久 ID。
4. da_download_page(page_id="kb2007…", destination=…) 会保存各页面供阅读，并附上类似以下的引用信息：*Røros 教区教会簿，1860-1878 年（1640P），AV/SAT-A-1456/681/L0932，第 171 张图像，共 464 张（kb20070419660172）。挪威国家档案馆（The National Archives of Norway），Digitalarkivet。 https://goto.digitalarkivet.no/kb20070419660172*。

设置

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

不克隆仓库。 uvx 会从 PyPI 获取并一步运行：

uvx norway-archives-mcp

从克隆的仓库运行，如果你打算修改代码，建议使用这种方式：

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

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

Claude Desktop

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

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

Claude Code

claude mcp add norway-archives -- uvx norway-archives-mcp

配置

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

变量	含义
NORWAY_ARCHIVES_CACHE_DIR	缓存目录，也用于存储每日请求计数。默认值为 ~/.cache/norway-archives-mcp。
NORWAY_ARCHIVES_TIMEOUT	单次请求的 HTTP 超时时间，单位为秒。默认值为 30。读取图片时超时设为 120 秒。
NORWAY_ARCHIVES_DA_INTERVAL	两次 Digitalarkivet 请求的最短间隔秒数。默认值为 5，且不能低于 5。
NORWAY_ARCHIVES_DA_DAILY_BUDGET	每个 UTC 日允许发送的 Digitalarkivet 实时请求数上限。默认值为 600。缓存结果不计入。
NORWAY_ARCHIVES_CONTACT	添加到 User-Agent 中的电子邮件地址或 URL，以便在你的使用导致问题时，档案馆可以联系你。可选，提供此信息会很周到。
NORWAY_ARCHIVES_DOWNLOAD_DIR	一个已存在的文件夹。设置后，下载内容只会保存到该文件夹中。将其设为 iCloud Drive 文件夹即可保存到该文件夹；它位于 ~/Library 下。

首次调用工具时，如果某个值不可用，系统会报告 not_configured 结果，并指出变量名称。

做个好访客，并了解相关条款

Digitalarkivet 未发布 API 或使用条款页面；其页脚仅链接到隐私和无障碍声明。其内容再利用页面称，不受限制的扫描件“kan disse fritt brukes videre både i trykksaker og på internett”：可以在印刷品和网络上自由再利用，但须注明馆藏档案出处 （digitalarkivet.no/content/1570）。 其 robots.txt 要求所有爬虫每次请求间隔五秒，并禁止一系列具名机器人，其中包括 AI Agent。本服务不是爬虫：它会逐个获取研究人员请求的页面，两次请求至少间隔五秒（只能调长），并设有每日请求上限，且会在 User-Agent 中注明自身身份。搜索、记录和来源页面的解析结果分别缓存 1、30 和 30 天；清单缓存 30 天；永久链接查询缓存一年。

挪威国家图书馆的 API 有文档说明，且无需密钥 （api.nb.no）。每项内容的访问权限遵循图书馆自身规则：标记为仅限挪威访问的资料，只能从挪威地址打开（海外研究人员可申请访问 Bokhylla 馆藏）；本服务会如实报告这一限制，而不会绕过它。每秒最多发送一个请求。

Kartverket 地名 API 无需登录或授权，用其自己的话说就是“ikke nødvendig med innlogging/autorisasjon” （api.kartverket.no/stedsnavn）。 每秒最多发送两个请求。

收到 429、5xx 响应或连接中断时，会重试一次，并遵循 Retry-After。如果遇到机器人检测，会报告为 blocked，不再继续尝试。

如何解读返回结果

• 转录内容不等于原始记录。 引用姓名、日期或关系前，请先查看扫描页面（da_download_page）。
• 没有结果并不代表一无所有。 da_search_persons 只搜索了转录的名册。da_search_sources 会显示哪些名册已扫描但无法搜索；确认名册和移民名册通常属于此类。请翻阅这些名册。
• 行政区划曾有变动。 da_ 工具按 Digitalarkivet 使用的历史市镇筛选（参见 municipalities）；place_names 返回的是 2020 年及更早合并后的现行市镇。
• 章节边界只是大致划分。 da_get_source 会返回某份名册起始页的图片；通常会一直延续到下一份名册开始，但书籍并不总是按顺序整理。
• 仅限挪威访问的书籍仍会返回结果。 即使无法在此处显示页面，nb_search_inside 仍会提供命中内容所在的印刷页码。
• 人口普查页面（ID 以 ft 开头）仅能通过旧版查看器以完整分辨率查看。

刻意不提供的功能

• 撰写任何内容或登录。 没有任何工具会向任何服务发送更正、报告或消息。
• 挪威历史人口登记册（HBR），其搜索功能是一个表单，API 仅供合作伙伴使用。
• Norway Heritage，其条款禁止未经许可进行复制或再分发。
• 绕过访问规则：仅限挪威访问的资料、近期受限记录或机器人检查。

安全

工具参数由模型编写，而模型会读取此服务无法控制的文本：记录转录、目录条目、OCR 内容。此服务假定这些文本可能会引导模型，并限制模型在受引导后能做的事情。

• 主机范围。 请求只会通过 https 发送到三个服务的固定主机。任何其他主机都会被拒绝，包括从响应中获取的地址。重定向只会在同一服务内跟随。
• 数据量限制。 超过 8 MB 的页面或 JSON 响应，以及超过 60 MB 的图像，在流式传输时都会被拒绝。
• 文件限制。 下载会创建一个新文件，绝不覆盖现有文件。数据必须是 JPEG，依据其开头字节判断，且文件扩展名必须为 .jpg 或 .jpeg。文件不能是隐藏文件或文件夹，不能位于 ~/Library 下；设置了 NORWAY_ARCHIVES_DOWNLOAD_DIR 时，文件也不能位于该目录之外。以上判断均在解析链接后进行。下载被拒绝时，磁盘上不会留下任何内容。
• 参数会经过验证（页面 ID、项目 ID、记录地址），然后才会用于请求。
• 网站文本不受信任。 服务会指示模型将记录和目录文本视为需要权衡的资料，而绝非指令。

如需报告漏洞，请参阅 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 services

有关测试套件的组织方式，请参阅 CONTRIBUTING.md；有关对各项服务的观察及观察时间，请参阅 docs/API-NOTES.md；有关服务采用这种设计的原因，请参阅 docs/DESIGN.md。

致谢

记录、扫描件和目录归 Nasjonalarkivet、Nasjonalbiblioteket 和 Kartverket 所有。大多数教会簿册转录由 AMF（Ancestry、MyHeritage 和 FamilySearch）根据与国家档案馆的协议制作。

许可证

MIT。