NARA Catalog

nara-catalog-mcp

US National Archives Catalogでの系譜調査に使えるMCPサーバーです。先祖の年金記録、従軍記録、国勢調査のページを探し、機械やボランティアが書き起こした内容を読み、引用するページ画像を取得できます。また、Catalogでは検索できないNARAのAccess to Archival Databases（AAD）も検索できます。検索対象には、NUMIDENTの社会保障申請記録と死亡記録、第二次世界大戦時の陸軍入隊カード、1820～1912年の船客名簿などがあります。

慎重な系譜調査者と同じように動作します。目録の説明は調査の手がかりであり、OCRテキスト、書き起こし、タグは、いずれも誰かがページを読んだ結果です。すべて手がかりにすぎません。情報源はページ画像です。どちらがどれに当たるかをツールが示し、引用する前に画像を読むよう、サーバーがモデルに指示します。

このサーバーはCatalogに書き込みを行わず、家系図も保存しません。記録を見つけて読み取りますが、そこから導き出した結論は、系譜調査用ソフトウェアか、このサーバーと併せて動かす家系図用MCPサーバーに保存してください。

ツールはCatalogに記載されたあらゆる記録で使えるため、歴史家やジャーナリストにも活用できます。本文中の例はすべて人物の調査を扱っています。

これは独立したプロジェクトです。National Archives and Records Administrationとは提携しておらず、同機関からの承認や支援も受けていません。

ツール

このサーバーは21個のツールを公開しています。20個は読み取り専用で、クライアントに読み取り専用として注釈されています。残る1個のdownload_page_imageはローカルディスクに新しいファイルを書き込みますが、既存のファイルを上書きすることはありません。

記録を探す

ツール	目的
search_records	タイトルまたは全文で検索します。総件数に加えて、NAID、階層、所蔵機関、対象期間、画像数を含む簡潔な概要を返します。各シリーズには作成者と作成した機関が記載されるため、タイトルが同じ複数のシリーズを区別できます。
search_records_advanced	同じ検索に、よくある名前を絞り込むフィルターを加えます。日付範囲、記録群、コレクション、先祖のNAID、記述レベル、マイクロフィルム出版番号、ローカル識別子、任意の管理番号、議会番号、参照部門、作成者、人物または組織、場所、資料の種類、繰り返しの日付、デジタル化済みの記録のみ、「書き起こし／タグ／コメントあり」、識別子の完全一致、10,000件を超える検索結果をページ分割するsearch_afterカーソル、さらにリクエストに応じて各検索結果のOCRテキスト（NARAおよびパートナー提供）を含める機能があります。
browse_children	ノード直下の子要素を表示します。記録群からシリーズ、ファイル単位、アイテムへとたどれます。信頼できるシリーズから下位へ進みます。

記録を読む

ツール	目的
get_record	NAIDを指定して1件の記録全体を読み取ります。範囲と内容に関する注記、階層、参照部門、オブジェクトID付きのすべてのページ画像を取得します。
get_record_images	ページ順にページ画像を取得します。各画像にはオブジェクトIDとURLが付いています。引用する前に確認する証拠です。
download_page_image	ページ番号、またはOCRや書き起こしの項目に記載されたオブジェクトIDを指定して、ページを新しいローカルファイルに保存します。メディアホストは公開されているため、APIの利用枠を消費しません。
get_online_availability	商業パートナーが公開しているものを含め、記録がオンラインで公開されている場所を調べます。
get_partner_digital_objects	商業パートナー（Ancestryなど）がこのNAIDに紐付けたデジタルオブジェクトIDを取得します。多くの場合、リストは空です。

機械や他の人が読み取った内容

このグループに含まれるものはすべて、文書を別の人が読んだ結果です。どのページを開けばよいかは分かりますが、そのページに何が書かれているかを示すものではありません。

ツール	目的
get_extracted_text	デジタルオブジェクトごとに、ページ画像から OCR で抽出したテキストと、その作成者、オブジェクトの総数、ファイルの処理に複数回の呼び出しが必要な場合は次の結果ページを取得します。
get_transcriptions	市民による翻刻です。OCR では読み取れない手書きの年金ファイルを読む手がかりになります。
get_tags	市民が付けたタグです。系譜記録では通常、ファイル内に登場する人物の名前が付けられています。
get_comments	他の研究者による記録へのメモです。

カタログではなく文書を検索する

ツール	目的
search_by_contribution_text	翻刻、タグ、コメント、OCR テキストを検索し、記録の概要全体を取得します。
search_transcriptions	翻刻テキストに名前やフレーズが記載されている記録を検索します。
search_tags	タグが付いた記録を、完全一致または単語で検索します。
search_extracted_text	パートナーが提供した抽出テキストに一致する記録を検索します。
search_comments	他の研究者がコメントした記録を検索します。

NARA の Access to Archival Databases（AAD）

AAD では、NARA の電子記録の一部を検索可能な表形式で提供しています。 各行は、機関の職員が記録から入力したデータベース項目です。電子記録として引用される翻刻または索引項目であり、記録そのものではありません。これらのツールにキーは不要で、Catalog の利用枠も消費しません。

ツール	目的
aad_list_series	AAD カテゴリ内のシリーズ（デフォルトでは系譜）と、それぞれに含まれるファイルおよびその ID を取得します。検索は 1 つのファイルを対象に実行されます。
aad_search	1 つのファイルを対象に、行全体のフリーテキスト検索と名前付きフィールドによる検索を実行します。1 ページにつき 50 行で、それぞれに記録 ID が付いています。
aad_get_record	1 行分の全情報を取得します。意味を含むコード値すべてと、取得日を含む NARA 推奨形式の引用情報も取得します。

管理

ツール	目的
api_budget	このセッション中のライブ呼び出し数とキャッシュヒット数、キャッシュと並ぶ台帳に記録された今月のライブ呼び出し数、キーの月間利用枠の残りを表示します。

セットアップ

Python 3.11 以降、uv、および Catalog API キーが必要です。Catalog API チームに API ドキュメント経由でキーを申請してください。 デフォルトの利用枠は月 10,000 回です。

サーバーの実行方法は 2 通りあります。

クローンせずに実行する場合。 uvx が PyPI から取得して一度に実行し、結果をキャッシュします。

NARA_API_KEY=your-key uvx nara-catalog-mcp

クローンから実行する場合は、変更を加える予定があるときに適しています。

git clone https://github.com/ianderso/nara-catalog-mcp
cd nara-catalog-mcp
uv sync
cp .env.example .env      # then put your key in it
uv run nara-catalog-mcp   # stdio server, usually launched by the client

どちらの場合も、サーバーは stdio 経由で MCP を使用します。そのため通常は、手動で実行するのではなく、MCP クライアントから起動します。

Claude Desktop

クローンせずに実行する場合：

{
  "mcpServers": {
    "nara": {
      "command": "uvx",
      "args": ["nara-catalog-mcp"],
      "env": { "NARA_API_KEY": "your-key" }
    }
  }
}

クローンから実行する場合（キーがクローンの .env にある場合は、env ブロックを省略できます）：

{
  "mcpServers": {
    "nara": {
      "command": "uv",
      "args": ["--directory", "/path/to/nara-catalog-mcp", "run", "nara-catalog-mcp"],
      "env": { "NARA_API_KEY": "your-key" }
    }
  }
}

デスクトップアプリでは、シェルの PATH が常に引き継がれるとは限りません。uv または uvx が見つからずサーバーを起動できない場合は、which uvx が出力するフルパスを command に指定してください。

Claude Code

claude mcp add nara --env NARA_API_KEY=your-key -- uvx nara-catalog-mcp

または、キーを .env に保存したクローンから実行する場合：

claude mcp add nara -- uv --directory /path/to/nara-catalog-mcp run nara-catalog-mcp

設定

すべての設定は環境変数から取得されます。サーバーの起動ディレクトリにある .env ファイルは、環境に設定されていない値を補います。uv --directory を使う場合、対象となるのはクローンです。読み込まれるのはそのディレクトリのみで、親ディレクトリやパッケージのインストール先ディレクトリは読み込まれません。

変数	意味
NARA_API_KEY	Catalog API キーです。Catalog ツールには必須ですが、AAD ツールには不要です。
NARA_CACHE_DIR	レスポンスキャッシュのディレクトリです。デフォルトは ~/.cache/nara-catalog-mcp です。
NARA_TIMEOUT	HTTP タイムアウト（秒）です。デフォルトは 60 です。
NARA_MONTHLY_CALL_BUDGET	キーで許可されている月ごとの呼び出し数です。api_budget で報告されます。デフォルトは 10000 です。

キーが設定されていない場合、または値が使用できない場合は、最初のツール呼び出し時に、該当する変数名を示す not_configured の結果が返されます。

呼び出し予算

Catalog キーには月ごとの上限があり、多数の名前を一気に検索すると、予想以上に早く使い切ってしまいます。成功した応答はすべて、エンドポイントとクエリをキーとしてディスクにキャッシュされるため、同じ呼び出しを繰り返しても費用はかかりません。ライブ呼び出しはキャッシュの隣にある budget.json 台帳にも記録されるため、api_budget は今月の使用量を、このセッションのライブ呼び出しとキャッシュヒットだけでなく、セッションをまたいで報告します。拒否された呼び出しも、API に到達しているためライブ呼び出しとして数えられます。台帳が把握するのは1台のマシンと1つのキャッシュディレクトリです。正確な回数は Catalog 側のカウントを参照してください。

キャッシュの有効期限はありません。get_record、get_record_images、get_extracted_text、get_transcriptions、get_tags、または get_comments に refresh=true を渡すと、Catalog から回答を1件読み直します。これには1回分の呼び出しが必要で、キャッシュ済みのコピーが置き換えられます。新しい文字起こしやタグは時間の経過とともに追加されます。また、紙でしか残っていなかったファイルがデジタル化されることもあるため、特に再取得する価値があるのは「何も見つからない」というキャッシュ済みの回答です。NARA_CACHE_DIR を削除する方法も引き続き使えますが、その場合は今月の台帳もリセットされます。

最初の10,000件を超えて検索する

page は検索結果が10,000件を超えると機能しなくなります。よくある姓ではこの上限を超えることがあります。search_records_advanced はその境界に達すると paging_note を返します。検索を絞り込むか、search_after="*" を指定して再実行し、各応答の next_search_after の値を使って続けてください。

検索の動作

title は記録のタイトルに含まれる語句と一致するため、より的確なオプションです。事件ファイルには通常、人物名がタイトルに使われています。query は説明全体を検索します。範囲が広くノイズも多いため、タイトル検索で何も見つからなかった場合に使うのがよいでしょう。

検索結果は記録全体ではなく、要約として返されます。Catalog の生の記録はサイズが大きく、記録を開く価値があるかどうかという判断には、ほとんど関係のない情報が大半を占めています。

AAD を検索する

AAD には API がないため、aad_* はブラウザーと同じ方法でウェブページを読み取り、解析します。そのため、動作には次のような特徴があります。

• 一度に1ファイルです。 大きなシリーズは複数のファイルに分割され、検索対象はそのうちの1つです。NUMIDENT は申請、請求、死亡のエントリー種別ごと、および姓の範囲ごとに分割されているため、まず aad_list_series を使います。
• フィールド名で指定します。 fields={"LAST NAME": "PRESLEY", "DATE OF BIRTH (YEAR)": "1930-1935"}。州や国など、AAD がコードとして保存しているフィールドは、名前では検索できません。その意味を query に指定してください。query はコードの意味も含めて行全体を検索します。
• 意図的に時間がかかります。 リクエストは一度に1件ずつ行い、少なくとも2秒間隔を空けます。また、AAD は最初に「Please Wait」ページを返すため、通常、検索には2回のリクエストが必要です。回答は NARA_CACHE_DIR/aad に7日間キャッシュされます。aad_get_record に refresh=true を指定すると、行を再取得できます。
• 記録 ID は固定されていません。 NARA はファイルを再読み込みすることがあり、その際に行番号が変わる場合があります。古い ID を再利用せず、もう一度検索してください。また、行を引用する際は、フィールド、ファイル、シリーズを明記してください。
• 行そのものが記録ではありません。 行は SS-5、パンチカード、またはマニフェストからキー入力されたもので、その際の入力ミスを含む可能性があります。また、すべての人を収録したファイルはありません。NUMIDENT にエントリーがあるのは、死亡が確認された人、または1908年より前に生まれた人だけです。また、NUMIDENT の死亡ファイルには州が報告した死亡は含まれません。各回答にはファイルに関する AAD 独自の注意書きが含まれており、NUMIDENT の回答にはそのファイルに収録されていない情報も記載されています。

注意事項

• 説明は根拠ではありません。 ファイルの概要を示すものであり、個々のページに何が記載されているかはわかりません。引用する前に画像を確認してください。
• OCRも文字起こしも根拠ではありません。 get_extracted_text は手書き文書のスキャン画像を機械が読み取ったもので、get_transcriptions はボランティアが入力した未確認のテキストです。どちらも該当ページを見つけるには最速の手段ですが、いずれも出典にはなりません。画像を開いて引用してください。
• NAIDを記録してください。 引用元を再び見つけるための、変わらない識別子です。
• すべての記録がデジタル化されているわけではありません。 image_count: 0 は説明が存在するものの、ページはオンラインにないことを意味します。reference_units フィールドには、紙の資料を所蔵する公文書館が示されています。
• 公開されていても、無制限に使えるとは限りません。 メディアホストにはキーなしでアクセスでき、NARA所蔵資料の大半はパブリックドメインですが、すべてではありません。説明に利用制限が記録されている場合もあります。画像を再公開する前に確認してください。

意図的に含めていない機能

Catalog APIではタグやコメントを投稿したり、文字起こしを登録したりできます。このサーバーではそれらを行いませんし、デフォルトで行うこともありません。投稿は設定されたキーの所有者名義で公開され、ここから取り消すことはできません。

セキュリティ

• キーは環境変数から読み込まれ、x-api-key ヘッダーとして catalog.archives.gov にのみ送信されます。メディアホストやAADには送信されず、レスポンスキャッシュにも保存されません。
• AADクライアントがアクセスするホストは1つだけです。 リクエストフックが aad.archives.gov 以外のホストを拒否するため、モデルが渡す値によって別のサイトを取得することはできません。Googlebotなどのクローラーが使う形式の Mozilla/5.0 (compatible; nara-catalog-mcp/<version>; +<this repository>) をユーザーエージェントとして送信します。試行時、AADのロードバランサーは単純な nara-catalog-mcp/<version> 形式に403を返しました。詳しくは docs/API-NOTES.md を参照してください。
• 投稿内容は信頼できないテキストです。 タグ、コメント、文字起こしは一般の利用者が書いたもので、モデルにはそのまま渡されるため、モデルに向けた指示が含まれている可能性があります。サーバーの指示では、そうしたテキストを指示ではなく検討対象の資料として扱うようモデルに伝えています。それでも判断するのはモデル自身なので、モデルが実行しようとする内容を確認してください。
• download_page_image はファイルを書き込みます。 サーバーのユーザーが書き込み可能な場所に新しいファイルを作成し、既存のファイルは上書きしません。そのため、誤ったパスや悪意を持って挿入されたパスによって何かが破壊されることはありません。読み取り専用ではないと注記されているため、クライアントは呼び出しごとに確認を求めることができます。

脆弱性を報告するには、SECURITY.md を参照してください。

開発

uv sync --extra dev
uv run pytest                # mocked with respx; no API key needed
uv run ruff check .
uv run ruff format --check .
uv run python -m tests.live_check   # needs a key: asks the Catalog what the mocks cannot

ライブチェックでは、モックでは確認できない点をCatalogに問い合わせます。2つのテキストフラグがテキストをどこに配置するか、サーバーがどの検索パラメーターを送信しないか、検索の要約に各シリーズの作成者名が引き続き含まれているかを確認します。また、AADが引き続きクライアントを受け入れるか、パーサーが引き続きページを読み取れるかも確認します。 どちらかに変更を加えたら実行してください。差異があれば出力に表示されます。

テストスイートの構成と、変更に必要な内容については、CONTRIBUTING.md を参照してください。

APIに関する注意事項

公開されているOpenAPI仕様には、特定の箇所に繰り返し確認される不正確さがあります。誤った required フラグ、maxLength の代わりに使われている maximum、そしてページネーションカーソルに関する相反する2つの定義です。ライブのCatalogで確認した修正内容は、docs/API-NOTES.md に記載されています。サーバーがこのような設計になっている理由、意図的に対象外としている範囲、テストスイートの構築方法については、docs/DESIGN.md を参照してください。

ライセンス

MIT。