Matricula Church Books

matricula-mcp

Matricula Online （data.matricula-online.eu）向けのMCP サーバーです。Matricula Online は、ICARUS（International Centre for Archival Research）がドイツ、オーストリア、ポーランド、スロベニア、セルビア、イタリア、スイス、ルクセンブルク、ボスニア・ヘルツェゴビナの教区や公文書館向けに運営する教会記録ポータルです。Matricula は、各ページをスキャンした教区簿（洗礼、婚姻、埋葬の記録と、それに付随する索引、家族簿、教区の国勢調査記録）を公開しています。独自の集計によると、2026年10月時点で約13,400の教区が登録されています。

このサーバーは、Matricula 独自の階層構造をたどります。国とその「セクション」（それぞれが教区、公文書館、または個人コレクションです）、座標付きのセクション内の教区、登録記号・種類・年代を含む教区の記録簿、そして Matricula 独自のビューアーで開くリンクとラベルが付いた記録簿のページを一覧表示します。また、Matricula の地名検索も実行し、ある村が属していた教区を見つけます。

慎重な系譜研究者と同じ方法で動作します。証拠となるのは記録簿のページです。 記録簿の種類や年代、ページラベル、検索結果の抜粋は、どのページを開くかを示す検索補助情報です。すべての結果には、ページを再び見つけるために Matricula 自身が示す順序（教区または公文書館、教区、記録簿の登録記号、ページ）で出典情報が付いています。

ページ画像は Matricula のビューアーで閲覧します。このサーバーは画像を取得しません。 Matricula の画像ホストはスクリプトからのリクエストを拒否しており、このサーバーはそれを回避するためにブラウザーを装うことはありません。ページ画像を保存するコードは文書化され、テスト済みですが、無効になっています。これは、ICARUS が身元を確認できるクライアントへのアクセスを許可したときに備えたものです。ページ画像をご覧ください。

このプロジェクトは Matricula に何も書き込まず、家系図を保持することもありません。

これは独立したプロジェクトです。Matricula が記録簿を公開している ICARUS、公文書館、教区とは提携関係になく、承認や支援も受けていません。

ツール

サーバーは7つのツールを公開します。matricula_page_image以外はすべて読み取り専用です。このツールは、画像アクセスが有効な場合にのみ新しいファイルを作成し、既存のファイルを上書きすることはありません。

検索

ツール	用途
matricula_sections	各国と、その国にあるセクション（教区とアーカイブ）、およびMatriculaの教区数を返します。
matricula_parishes	1つのセクションに属する教区を、座標およびセクション独自の注記（アーカイブの住所であることがよくあります）とともに名前で絞り込んで返します。
matricula_search	Matriculaの地名検索です。地名が名前または説明に記載されている教区と、該当箇所を示す抜粋を返します。セクションまたは期間内の登録簿で絞り込むこともできます。

閲覧

ツール	用途
matricula_registers	教区の登録簿について、署名、アーカイブ独自の種別（Taufen、Trauungen、Sterben、Index - ...）、種類（洗礼、婚姻、埋葬など）、日付、内容の注記、原本の所蔵先、および各登録簿のキーを返します。
matricula_register	1つの登録簿について、説明と引用情報、および各ページの位置、ラベル、ビューアーリンクを、ページ送りとラベルによる絞り込みとともに返します。
matricula_page_image	オペレーターが画像アクセスを有効にするまでオフです。オフの間は、ページのビューアーリンク、ラベル、引用情報とともにimages_not_enabledを返します。有効にすると、引用情報を添えて1ページを新しい.jpgとして保存します。
cache_status	このセッションでのリクエスト、リクエスト間隔、キャッシュの使用状況、画像アクセスの有効・無効を返します。リクエストは行いません。

すべての項目は、言語プレフィックス以下にあるMatricula上のパスで指定します。ツールではこれをキーと呼びます。deutschland/passauはセクション、oesterreich/salzburg/krimmlは教区、oesterreich/salzburg/krimml/TFBIは登録簿です。すべてのツールで、Matriculaのどのインターフェース言語のアドレスも指定できます。また、登録簿に関するツールでは、ページのビューアーアドレス（?pg=N）を指定できます。

セットアップ

Python 3.11以降とuvが必要です。申請が必要なキーはありません。

クローンせずに使う場合。 uvxでPyPIから取得し、1つの手順で実行できます。

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]" }
    }
  }
}

デスクトップアプリでは、シェルの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	1回のリクエストに対する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はそのフォルダー内にのみ保存します。~/Library以下にあるiCloud Driveフォルダーに保存するには、そのフォルダーを指定します。
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 を設定してください。その後、ツールは画像ホストから一度に 1 ページを取得します。他のすべてのリクエストと同様に間隔を空け、このサーバー独自の 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 は、アーカイブ協会が運営する単一のサービスです。クライアントは一度に 1 件のリクエストを送信し、リクエスト間を少なくとも 2 秒空けます。また、場所の検索は、ポータル内のすべての教区の説明を読み込むため、前回のリクエストから少なくとも 10 秒後に行います。国とセクションの一覧、および教区の一覧は 28 日間、教区と台帳のページは 7 日間、検索結果は 1 日間キャッシュされます。2 件の同一の呼び出しが同時に実行された場合は、1 件のリクエストを共有します。429、5xx、または接続切断が発生した場合は、Retry-After に従って 1 回だけ再試行します。拒否された場合は再試行しません。User-Agent には、パッケージ名、バージョン、このリポジトリ、および設定されている場合は連絡先が記載されます。Cookie は保持しません。

Matricula の利用規約について

data.matricula-online.eu の利用規約（ドイツ語、2026-10-11 確認）は、画像と記述メタデータを対象としています。

• すべての教会台帳の画像は 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: / が指定されています。また、ほかのすべてのエージェントに対し、4 種類のアドレス、すなわち閲覧ページのパラメーター（/*?pg=）、検索（/*/suchen）、地図機能（/*/landkarte-features）、アカウントにはアクセスしないよう求めています。このサーバーはクローラーではありません。研究者が指定したページを一度に 1 ページずつ読み取り、キャッシュします。検索（matricula_search）と、各セクションにつき地図機能ファイルを 1 つ（matricula_parishes の座標用）読み取ります。人が開くための ?pg= リンクを生成しますが、そのリンクにはアクセスしません。アカウントには一切触れません。この利用方法が適切かどうかは、ご自身でご判断ください。

取得した内容の読み方

• 階層を引用し、リンクは場所を示すものとして扱います。 Matricula は、教区またはアーカイブ、教区、台帳の記号、ページをたどってページを再び見つけるよう案内しており、リンクが永続するとは保証していません。各結果の citation にはこの順序で記載され、cite_as には 1 文でまとめられています。
• 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 として報告し、それ以上処理しません。

セキュリティ

ツールの引数はモデルが作成し、モデルはこのサーバーが制御できないテキストを読み取ります。サーバーは、そのテキストがモデルを誘導する可能性を想定し、誘導されたモデルにできることを制限しています。

• 接続先ホスト。 リクエストフックは、ページから取得したアドレスも含め、data.matricula-online.eu 以外への HTTPS 以外の接続を拒否します。画像へのアクセスが無効な間は、画像ホストへの接続も拒否します。リダイレクトは同じホストへの場合に限り追跡します。
• ページ。 キーは正しい数の部分で構成され、それぞれが Matricula のスラッグで使われる文字のみでなければなりません。それ以外（..、別のホストなど）は、検索する前に拒否されます。
• アドレス。 接続のたびに接続先を確認します。プライベート、ループバック、リンクローカル、CGNAT、マルチキャスト、予約済み、または未指定のアドレス（IPv4、IPv6 のいずれも）に解決される名前は拒否し、確認したアドレスに接続します。環境変数のプロキシ設定は使用しません。
• データ量。 8 MB を超えるページ、または 60 MB を超える画像は、ストリーミング受信中に拒否されます。
• ファイル。 matricula_page_image は新しいファイルを 1 つ作成し、既存のファイルを上書きしません。また、画像へのアクセスが有効な場合に限り作成します。最初のバイトから 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 に問い合わせます。カタログページのみ（約 12 件）を 2 秒間隔で読み取り、検索を 1 回行います。画像ホストへのアクセスは行いません。テストスイートの構成については CONTRIBUTING.md を、サイトで確認された内容とその時期については docs/API-NOTES.md を、サーバーがこの設計になっている理由については docs/DESIGN.md をご覧ください。

クレジット

台帳は、それらを保管する教区、文書館、教会に帰属します。画像は、Matricula を通じてそれらの機関が CC BY-NC-ND 2.0 の下で公開しています。Matricula は ICARUS が運営しており、利用者に支援を呼びかけています。

ライセンス

このサーバーのコードは MIT ライセンスです。リンク先の画像と説明は、Matricula の利用規約に従います。