internet-archive-mcp-server

---

概要

Wayback Machine と Internet Archive ライブラリ（4,000 万件以上のアイテム）を利用できます。任意の URL のアーカイブ済みスナップショットを検索・取得し、キーワードやメタデータでライブラリを検索して、アイテムのメタデータ、ファイルマニフェスト、OCR テキストを取得できます。

ツール

ツール	説明
ia_find_snapshots	URL の Wayback Machine スナップショットを、最も近いタイムスタンプまたはすべての保存履歴から検索します
ia_get_snapshot	指定した Wayback タイムスタンプのアーカイブ済みページコンテンツを取得します
ia_search_items	キーワードとメタデータフィルターを使って IA ライブラリ（4,000 万件以上のアイテム）を検索します
ia_get_item	Archive アイテムの完全なメタデータとファイルマニフェストを取得します
ia_get_text	テキストアイテムから、ページ指定に対応した読み取り可能な OCR テキストを取得します

リソース

リソース	説明
ia://item/{identifier}	Archive アイテムのメタデータスナップショット — タイトル、作成者、メディアタイプ、説明、主題、コレクション、日付、ライセンス、ファイル数

リソースのデータはすべて ia_get_item からも取得できます。

機能リファレンス

ia_find_snapshots _ツール

• closest モード：Availability API を通じて、指定された timestamp に最も近いキャプチャを返します。Availability API が回答を返さない場合は、CDX の最も近いキャプチャを検索するクエリを 1 回実行してフォールバックします（200 のキャプチャを優先し、期限は 25 秒です）
• history モード：CDX API を通じてキャプチャの全一覧を返します。日付範囲（from／to）と HTTP ステータス（status_filter）で絞り込みます
• timestamp:N で折りたたむ正確な URL の場合、ページ境界を飛ばさずに続行するには、返された resume_key を同じ URL とともに渡してください。カーソルは 1 時間後に期限切れとなり、元のフィルターを保持します。ページ間で limit は変更できます。無効なカーソルは invalid_resume_key を返し、明示的なフィルターが競合する場合は resume_key_conflict を返します。従来の CDX キーとワイルドカード履歴も引き続き利用できますが、ページによってはキャプチャが省略される可能性があるという通知が表示されます
• collapse は省略または空欄の場合、timestamp:8（1 日につき 1 キャプチャ）です。timestamp:N に変更でき、N は 1～14 です。timestamp:14 では、キャプチャの秒単位の時刻ごとに 1 行を表示します
• 1 回の呼び出しにつき最大 10,000 件（limit、デフォルトは 100）です。より大きな limit（最大 150,000）を指定した場合は 10,000 件ずつ返され、キャプチャが残っているときは truncated が設定され、resume_key を示す notice が返されます。大量の履歴には resume_key によるページネーションを使用します
• リプレイ URL は常に https://web.archive.org/web/… です
• 型付きエラー：missing_timestamp（timestamp を指定しない closest モード。検索前に返されます）、no_snapshots（一致するものがありません）、no_snapshot_available（closest モードで、いずれのソースからも指定時刻付近のキャプチャが見つからない場合。また、どちらのモードでも、Wayback Machine が URL を配信しない場合。除外対象のサイトと同様に、403、410、451 が返されます）、cdx_unavailable（CDX の 5xx、429、その他の 4xx、タイムアウト、ネットワークエラー、または読み取り不能な応答が発生した場合、あるいは closest モードの CDX チェックが完了しなかった場合）、availability_unavailable（closest モードで、Availability API の 5xx、429、その他の 4xx、タイムアウト、ネットワークエラー、または読み取り不能な応答が発生した場合）。429、その他の 4xx、またはリクエストタイムアウトの場合は、リクエスト 1 回で応答します。429 には待機するようヒントが示され、4xx にはリクエストを再試行しても解決しないというヒントが示されます

---

ia_get_snapshot _ツール

• 指定した正確なタイムスタンプにスナップショットがない場合、最も近い利用可能なキャプチャを解決先として返します。正確な 14 桁のタイムスタンプでは解決処理をスキップします
• Wayback が配信したキャプチャを報告します。指定したタイムスタンプ自体がキャプチャではない場合、replay_url、resolved_timestamp、resolved_status は Wayback のリダイレクト先に従います
• 宣言された文字セット（Content-Type、次に <meta>。どちらもない場合、バイト列が有効な UTF-8 なら UTF-8、それ以外は Wayback が推測した文字セットまたは windows-1252）を使ってページをデコードし、スクリプト、スタイル、コメント、タグを削除して文字参照をデコードした後、リプレイ URL とともに読みやすいプレーンテキストを返します
• ページの先頭 4 MiB までを読み込みます（ページがそれより長い場合は notice で通知されます）。出力は IA_MAX_SNAPSHOT_CHARS（デフォルトは 50,000 文字）で上限が設定されています
• 型付きエラー：no_snapshot_available（指定時刻付近にキャプチャがない場合、キャプチャがアーカイブされたエラーページである場合（メッセージにタイムスタンプとアーカイブ時のステータスが示されます）、Wayback がリプレイを 4xx で拒否した場合、または Wayback Machine の検索が 403、410、451 で拒否された場合。除外対象のサイトと同様です）、content_fetch_failed（Wayback に到達できない、レート制限を受けている、検索を拒否されている、または検索中もしくは取得中にタイムアウトした場合）

---

ia_search_items _ツール

• Solr のクエリ構文と、mediatype、collection、creator、language、日付範囲（date_from／date_to）の構造化フィルターに対応します
• 日付の境界には YYYY、YYYY-MM、YYYY-MM-DD を指定できます。date_from には期間の初日、date_to には最終日が適用され、うるう年も考慮されます。境界が空欄の場合、その側には上限や下限を設けません。無効な日付は、検索リクエストを送信する前に invalid_date_range を返します
• mediatype には Internet Archive の10種類のメディアタイプ（texts、movies、audio、software、image、data、web、collection、etree、account）を、大文字と小文字を区別せずに指定できます。また、よくある類似の値も解決されます（text、book、books → texts、movie、video、videos → movies、images → image、collections → collection）
• ダウンロード数、日付、タイトル、またはランダムで並べ替えます（sort。date asc や titleSorter asc などの Solr 構文を使用。デフォルトは downloads desc。Advanced Search には関連度順の並べ替えはありません）。同じ並べ替え値の項目は identifier 順になるため、連続するページで項目が重複したり抜けたりしません
• query は最大2,047文字です。これは Advanced Search が受け付ける最長の長さです。フィルターも文字数に含まれます。クエリ内の URL は引用符で囲む必要があります
• 1回の呼び出しで最大200件の結果を返します（rows、デフォルトは50）。page は1始まりです。1ページ目で rows に200を超える値（最大10,000）を指定した場合は、200件として処理されます。結果がさらにある場合は truncated が設定され、rows: 200, page: 2 を示す notice が返されます
• Advanced Search が返すのは最初の10,000件のみであるため、page × rows ≤ 10,000 を満たす必要があります
• 出力には、ページネーションに適用された total_found、page、rows が含まれます。該当する結果がないページではエラーではなく notice が返されます。何も一致しない場合は適用された mediatype が、page が最終ページを超えている場合は最終ページが示されます
• title、date、creator、collection は文字列またはリストで指定できます。collection ではアカウントごとの fav- お気に入りリストは除外されます。creator には最初の10件が表示され、レコードにそれ以上ある場合は creator_count も返されます
• 検索リクエストを送信する前に返される型付きエラー：invalid_date_range（日付の境界が無効）、invalid_mediatype（その他の mediatype。受け付ける値を列挙）、rows_over_cap（1ページ目より後で rows が200を超えている）、page_limit_exceeded（page × rows が10,000を超えている。到達可能な最終ページを示す）
• Advanced Search が返す型付きエラー：invalid_query（クエリ構文、引用符で囲まれていない URL、フィルターを含めると2,047文字を超えるクエリ、または並べ替えフィールドが拒否された場合。メッセージもそのまま伝達されます）、search_unavailable（検索に失敗した場合、リクエストがレート制限された場合、読み取れない応答が返された場合、タイムアウトした場合、または接続できなかった場合）。5xx エラーまたはネットワークエラーの場合は再試行します。429、その他の4xx、タイムアウト、またはエラーボディの場合は1回のリクエスト後に応答します。4xx の場合は、リクエストを繰り返しても解決しない旨のヒントが含まれます

---

ia_get_item _ツール

• 上流のメタデータに存在する場合、title、creator、description、subject、collection、licenseurl、rights、language を返します。creator、description、subject、collection、language は文字列またはリストの場合があります
• files[] には、上流の順序でマニフェストの1ページ分が含まれます。各ファイルについて format、size、md5、直接ダウンロードできる download_url が返されます。file_count は常にマニフェスト全体のサイズです
• 大きなアイテムは、max_files（デフォルトは50、1回の呼び出しで最大500）と file_offset（デフォルトは0）でページ分割できます。max_files に500を超える値（最大300,000）を指定した場合は、500として処理されます。ファイルが残っている場合、応答に truncated が設定され、次の file_offset が示されます
• ページ分割の前に format で1種類のファイル形式を絞り込みます（一致条件は完全一致、大文字と小文字は区別しません。例：DjVuTXT、Text PDF、VBR MP3）。一致件数は totalCount として返されます。一致する形式がない場合は空のページが返され、そのアイテムが持つ形式を列挙した notice が表示されます
• 型付きエラー：item_not_found（不明な識別子、または非公開の識別子）、archive_unavailable（Metadata API が失敗した場合、リクエストがレート制限または拒否された場合、タイムアウトした場合、接続できなかった場合、または読み取れない応答が返された場合）。最初のタイムアウト後に1回再試行するため、呼び出しが待機する時間は最大でもリクエスト2回分のタイムアウトです

ia_get_text _ツール

• max_chars と char_offset を使って長いドキュメントをページ分割できます。has_more はテキストがまだ残っていることを示します。max_chars のデフォルト値は IA_MAX_SNAPSHOT_CHARS で、上限も同じ値です。より大きな値を指定した場合は、その上限値で処理され、notice が返されます。また、出力の max_chars には適用された値が示されます
• ページを順に取得するには、同じ identifier を指定し、char_offset を省略して、next_continuation を continuation として渡します。カーソルの有効期限は1時間で、ページは選択したテキストファイルに紐付けられ、バイト単位のチェックポイントから再開します。安定したファイルバリデーターまたはカーソルストレージを利用できない場合、レスポンスにはオフセット継続を示す通知が含まれます
• 継続取得時のエラー：トークンとオフセットの両方が指定された場合は ambiguous_pagination、カーソルが無効またはファイルが変更されている場合は invalid_continuation、保存された範囲からダウンロードを再開できない場合は range_unavailable です。エラーからの復旧方法として、使用すべき char_offset が示されます
• 上流からの読み取りはページの末尾で停止するため、呼び出しごとのメモリ使用量はページサイズによって制限されます
• 利用可能なテキストファイルのうち最適なものを特定します。DjVuTXT を優先し、利用できない場合はプレーンテキストにフォールバックします。source_file は取得したファイル名、source_file_bytes はアイテムマニフェストに記載されたファイルサイズ（バイト単位）です
• 型付きエラー：識別子が不明な場合は item_not_found、テキストファイルがない場合は no_text_file、制限付きコレクションの場合は download_forbidden、Metadata API またはテキストのダウンロードに失敗した場合、レート制限またはリクエスト拒否を受けた場合、タイムアウトした場合、到達できなかった場合は archive_unavailable です。メタデータリクエストとダウンロードは、それぞれ最初のタイムアウト時に一度だけ再試行し、2回目で停止します

---

ia://item/{identifier} _リソース

• application/json を返します。含まれる項目は title、creator、mediatype、description、subject、collection、date、licenseurl、rights、language、file_count です
• identifier は ia_search_items の結果から取得します
• 型付きエラー：不明な識別子の場合は item_not_found、Metadata API が失敗した場合は archive_unavailable です

機能

@cyanheads/mcp-ts-core をベースに構築されています。stdio および Streamable HTTP トランスポート、交換可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレース機能を備えた構造化ログに対応しています。

Internet Archive 固有の機能：

• 認証情報は不要です。4つの API はすべて公開されています
• 3つのサービスレイヤー：WaybackService（Availability + CDX）、ArchiveSearchService（Solr）、ArchiveMetadataService（Metadata + ダウンロード）
• CDX の日単位の折りたたみをデフォルトとし、設定可能な limit によって、キャプチャ数の多い URL のレスポンスを扱いやすく保ちます
• IA の利用規約で求められているとおり、すべてのリクエストにカスタム User-Agent を付けて識別します。IA_USER_AGENT で設定できます

エージェント向けの出力：

• すべてのリストレスポンスにページネーションのコンテキストを含めます。total_found、page、rows（検索）、resume_key（CDX 履歴）、file_count と次の file_offset（アイテムのファイル）が含まれるため、エージェントが結果の完了状況を推測する必要はありません
• 復旧のヒントを含む型付きエラー理由により、呼び出し元はエラーメッセージを解析せずに再試行したり、フィルターを修正したり、期限切れの継続情報から復旧したりできます
• 構造化されたファイルマニフェストを提供します。ia_get_item はファイル単位のメタデータ（形式、サイズ、URL）と format フィルターを返すため、エージェントはサムネイルを順に取得せずに適切なファイルを選択できます

はじめに

公開ホスト型インスタンス

https://internet-archive.caseyjhand.com/mcp で公開インスタンスを利用できます。インストールは不要です。Streamable HTTP を提供しており、各クライアントはそれぞれの設定形式を使用します。

Claude Code の場合：

claude mcp add --transport http internet-archive-mcp-server https://internet-archive.caseyjhand.com/mcp

Cline の場合（cline_mcp_settings.json）：

{
  "mcpServers": {
    "internet-archive-mcp-server": {
      "type": "streamableHttp",
      "url": "https://internet-archive.caseyjhand.com/mcp"
    }
  }
}

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "internet-archive-mcp-server": {
      "url": "https://internet-archive.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop では、Settings → Connectors からリモートサーバーを追加します。

セルフホスト／ローカル

API キーは不要です。Internet Archive の API はすべて完全に公開されています。

次の内容を MCP クライアントの設定ファイルに追加します：

{
  "mcpServers": {
    "internet-archive-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/internet-archive-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または npx を使用します（Bun は不要です）：

{
  "mcpServers": {
    "internet-archive-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/internet-archive-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または Docker を使用します：

{
  "mcpServers": {
    "internet-archive-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/internet-archive-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動します：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上（または Node.js v24 以降）。
• 外部アカウントや API キーは不要です。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/internet-archive-mcp-server.git

2. ディレクトリに移動します：

cd internet-archive-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# Optional: edit .env for custom User-Agent, timeouts, etc.

設定

すべての設定は、起動時に src/config/server-config.ts の Zod スキーマを使って検証されます。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http	stdio
MCP_HTTP_PORT	HTTP サーバーのポート	3010
MCP_AUTH_MODE	認証モード：none、jwt、または oauth	none
MCP_LOG_LEVEL	ログレベル（debug、info、notice、warning、error）	info
LOGS_DIR	ログファイル用のディレクトリ（Node.js のみ）	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド	in-memory
OTEL_ENABLED	OpenTelemetry の計測を有効にするかどうか	false
IA_USER_AGENT	IA API リクエスト用のカスタム User-Agent	internet-archive-mcp-server/{version} (github.com/cyanheads/internet-archive-mcp-server)
IA_REQUEST_TIMEOUT_MS	ヘッダーと本文を含む HTTP リクエストのタイムアウト（ミリ秒）。正の整数を指定してください。それ以外の場合、起動に失敗します	30000
IA_MAX_SNAPSHOT_CHARS	ia_get_text ページあたりのデフォルトおよび最大文字数（これを超える max_chars はこの値で提供されます）。ia_get_snapshot のテキストにも上限として適用されます。正の整数を指定してください。それ以外の場合、起動に失敗します	50000

省略可能な上書き設定の一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t internet-archive-mcp-server .
docker run --rm -p 3010:3010 internet-archive-mcp-server

Dockerfile では、デフォルトで HTTP トランスポートとステートレスセッションモードが設定され、ログは /var/log/internet-archive-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイント。ツールとリソースを登録し、サービスを初期化します。
src/config	Zod を使った、サーバー固有の環境変数の解析と検証。
src/mcp-server/tools	ツール定義（*.tool.ts）。Wayback と IA ライブラリにまたがる 5 つのツール。
src/mcp-server/resources	リソース定義。ia://item/{identifier} のアイテムメタデータリソース。
src/services/wayback	WaybackService — Availability API と CDX API のクライアントに加え、アーカイブされたページの文字コード判定とテキスト抽出を行います。
src/services/archive-search	ArchiveSearchService — Solr Advanced Search クライアント。
src/services/archive-metadata	ArchiveMetadataService — Metadata API とファイルダウンロードのクライアント。
tests/	src/ に対応する単体テストと統合テスト。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使わないでください。
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使います。
• src/mcp-server/*/definitions/index.ts のバレルを介して、新しいツールとリソースを登録します。
• 外部 API 呼び出しはラップします。生データを検証し、ドメイン型に正規化してから、出力スキーマを返します。不足しているフィールドを捏造しないでください。

コントリビューション

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。