earthquake-mcp-server

---

概要

USGS ComCat と EMSC SeismicPortal の地震データを提供します。リアルタイムの地震フィードを取得し、期間、マグニチュード、深さ、位置で地震イベントを検索・集計できます。また、特定のイベントの詳細な解析情報も取得できます。

ツール

ツール	説明
earthquake_get_feed	マグニチュードの区分と期間を指定して、USGS の事前計算済みリアルタイム地震フィードを取得します
earthquake_search_events	期間、マグニチュード、深さ、位置の半径、PAGER 警戒レベル、または有感報告で地震を検索します
earthquake_count_events	全レコードを取得せず、フィルターに一致する地震の件数を数えます
earthquake_get_event	USGS イベント ID を指定して、特定の地震の詳細情報を取得します

リソース

リソース	説明
earthquake://feed/{magnitude_tier}/{time_window}	USGS リアルタイムフィードの最初のページを上限付きで取得します。正確な続行 URI も含まれます
earthquake://feed/{magnitude_tier}/{time_window}/page/{cursor}	返された next_uri を使用して、保持されているフィード生成の続きを取得します
earthquake://event/{event_id}	ID で指定した USGS 地震イベントの全詳細を、コンテキストとして注入可能な形式で取得します。earthquake_get_event と同じ detail プロダクト投影を含みます

機能リファレンス

earthquake_get_feed _ツール

• マグニチュードの区分（all、1.0、2.5、4.5、significant）と期間（hour、day、week、month）を選択します。USGS はこれらのフィードをキャッシュするため、過去の期間やフィルターを指定した検索には earthquake_search_events を使用してください。
• イベント、ページ数、生成時刻、ソースフィードの URL を返します。all には微小地震が含まれます。significant は、マグニチュード、体感報告、PAGER による影響に基づいて USGS が選定したものです。
• limit のデフォルトは 100 で、最大 1000 まで指定できます。ページはシリアライズ後のサイズが 24,000 バイト以内になるため、含まれるイベント数が少なくなる場合があります。totalCount はフィード全体の件数を示します。nextCursor は、同じ区分と期間で変更せずに渡してください。
• 続きの読み込みでは、最初に読み込んだ時点の生成データが使われ、上流での編集の影響を受けません。保持期間は最大 15 分ですが、容量超過による削除や再起動の影響を受けます。cursor_expired が返された場合は、カーソルなしで最初からやり直してください。以前の形式のカーソルも最初からやり直す必要があります。

---

earthquake_search_events _ツール

• 時刻、マグニチュード、深さ、半径、または境界ボックスで usgs または emsc を検索します。半径を指定する場合は、latitude、longitude、radius_km をすべて指定する必要があります。ボックスの各辺は個別に省略可能で、±360°までの日付変更線をまたぐ境界に対応します。また、指定した円との積集合が使われます。
• event_type と EMSC の event_certainty を含む、正規化されたイベントを返します。ignoredFilters には未対応のフィルターが記載され、queryEcho には有効なクエリが示されます。
• 検索と件数取得のどちらも、いずれのソースでも任意の magnitude_type 値を受け付けます。product_type（必要なプロダクト。例：moment-tensor）と review_status（automatic または reviewed）は USGS にのみ適用されます。EMSC では、これらは ignoredFilters に記載されます。空白の値は未指定として扱われます。
• 日付のみの境界（拡張された年形式、年月形式を含む）は、両方のソースで指定日の午前 0 時を意味します。2026-10-10 は 2026-10-10T00:00:00 になります。明示的な時刻とタイムゾーン接尾辞はそのまま保持されます。ゼロ埋めされていない日付要素はゼロ埋めされます。タイムゾーンのない時刻には、デフォルトの 30 日間の期間で UTC が使われます。queryEcho には有効な境界が正確に表示されます。
• 時刻またはマグニチュードで昇順・降順に並べ替えます。limit のデフォルトは 100 で、最大 20,000 まで指定できます。各呼び出しで取得する候補は最大 100 件で、シリアライズ後のサイズが 24,000 バイト以内のページを返します。ページングでは、返された nextOffset の値をそのまま使用します（1 からカウント）。フィルターと順序は同じにしてください。queryEcho.limit には有効な上流候補件数の上限が示されます。検索ページは最新のカタログを読み込むため、上流での編集が後続のページに影響する場合があります。
• マグニチュード、深さ、または明示的な時刻の境界が厳密に逆転している場合は、両方の値と対処方法を示す invalid_range をローカルで返し、処理を失敗させます。同じ値の境界と片側のみの境界は引き続き有効です。時刻の比較には、明示的なオフセットを含め、UTC の時刻が使われます。暦上無効な値は上流での拒否に委ねられます。
• 上流から空でない短いページが返された場合、バイト数に合わせて整形する前に totalCount が確定します。最初のページが空の場合は 0 と確定し、後続のページが空の場合は不明のままです。上流から満杯のページが返された場合は件数照会が行われ、失敗すると countUnavailable が設定されます。フィードと検索のリクエストでは、再試行を含めて 50 秒の期限を共有します。検索にはオプションの件数照会も含まれます。キャンセルは引き続きキャンセルとして扱われます。

---

earthquake_count_events _ツール

• イベントを取得せず、earthquake_search_events と同じフィルターを使って一致件数を数えます。過去 30 日間を対象にする場合は start_time を省略してください。queryEcho には解決された期間と適用されたフィルターが示されます。
• exceeds_limit は、1 回のリクエストで 20,000 件を超えることを示すフラグであり、取得件数の上限を示すものではありません。検索のオフセットページングを使えば、それより多い一致件数も取得できます。max_allowed は USGS では 20,000、EMSC では null です。ignoredFilters には、ソースで適用できないフィルターが記載されます。

---

earthquake_get_event _tool

• フィードまたは USGS の検索結果にある id フィールドの USGS event_id を渡します（例：us6000sznj）。このツールが受け付けるのは、現在 USGS の ID のみです。
• 正規化されたイベントに加えて、任意の detail を返します。内容は PAGER、ShakeMap、DYFI、モーメントテンソル、地盤崩壊アラート、震源の品質、有限断層の寸法です。投影されたフィールドがないグループは省略されます。データがないことは、影響がゼロであることを意味しません。
• 空白の ID はローカルでエラーになります。正規 ID と別名は、大文字と小文字を区別せず照合されます。ShakeMap には、公開されている場合、提供元の code_version が含まれます。

---

earthquake://feed/{magnitude_tier}/{time_window} _resource

• earthquake_get_feed と同じマグニチュード区分と時間枠を選択できます。20 通りすべての組み合わせが、参照可能なリソースとして一覧表示されます。
• 既存のコンパクトなイベント投影を使用した、サイズ上限付きの application/json ページを返します。さらに totalCount、truncated、nextCursor、next_uri も含まれます。next_uri がなくなるまで、その値をそのまま読み取ってください。継続 URI は earthquake://feed/{magnitude_tier}/{time_window}/page/{cursor} です。
• フィードリソースは、earthquake_get_feed と保持済みの世代を共有します。継続トークンはリクエスト元のテナントに属するため、キャッシュヒントは非公開で、有効期間はゼロです。ServiceUnavailable に分類されるアップストリーム障害では feed_unavailable が、Timeout に分類される障害では feed_timeout が公開されます。どちらにも復旧方法が示され、アップストリームの応答本文は記録されません。可用性障害では数値の HTTP ステータスが保持されます。HTTP 501 は引き続き再試行不可で、EMSC の検索を案内します。その他のエラークラスは変更されずに伝播します。

---

earthquake://event/{event_id} _resource

• フィードまたは検索結果にある USGS event_id を渡します。earthquake_get_event と同じイベントおよび任意の detail プロダクトを返します。
• 同ツールの event_deleted、not_found、source_unavailable、source_timeout のエラー契約を使用します。

特徴

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

USGS／EMSC 固有の機能：

• USGS FDSN／GeoJSON API および EMSC FDSN-WS API 向けの型安全なクライアントを提供し、両方のデータを共通の地震ドメインスキーマに正規化します
• すべての上流呼び出しで、バックオフ付きの自動再試行とリクエストごとのタイムアウトを実行します。USGS のレート制限／CDN 障害モード（GeoJSON の代わりに HTML が返される状態）を検出し、データとして解析するのではなく、型付きのサービス利用不可エラーに変換します
• EMSC の 2 文字の evtype コードを、公開されているイベントタイプ／確実性の命名規則に基づいて、USGS が公開しているものと同じ用語に変換するため、両ソースで event_type の意味が統一されます
• source=emsc の場合、USGS 専用フィルター（alert_level、min_felt、min_significance、event_type、product_type、review_status）は ignoredFilters に記載されます。USGS では、event_type="earthquake" により、採石場の発破など、地殻変動以外の記録が除外されます。
• API キーやレート制限の階層は不要です。USGS と EMSC はどちらも完全に公開された、キー不要の API です

エージェントが利用しやすい出力：

• データの出所 — すべてのレスポンスに source: "usgs" | "emsc" が含まれ、さらにカタログと権威機関を示す source_catalog／auth フィールドも含まれるため、エージェントは独立した 2 つの解決結果を比較できます
• 識別可能な出力コントラクト — event_type と EMSC の event_certainty は公開済みの分類を保持し、存在しないフィールドは不明のままになります。exceeds_limit、countUnavailable、truncated フラグにより、呼び出し元は文章を解析せずにデータに基づいて分岐できます
• レスポンスの整形 — ソースが公開していないフィールドは、捏造したゼロ値ではなく null として返されます（EMSC のイベントでは tsunami、status、mmi は常に null です）。EMSC のクエリで除外された USGS 専用フィルターは、暗黙に無視されるのではなく ignoredFilters に記載されます
• グレースフルデグラデーション — 上流から拒否された場合、単なるステータスコードではなく、サービス独自の説明（問題のあるパラメーター、受け入れられる形式）がエラーメッセージに表示されます。また、後続の件数取得に失敗しても検索全体が失敗するのではなく、countUnavailable に切り替わります

はじめに

公開ホストインスタンス

https://earthquake.caseyjhand.com/mcp で公開インスタンスを利用できます。インストールは不要です。Streamable HTTP 経由で任意の MCP クライアントを接続してください。

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "type": "streamable-http",
      "url": "https://earthquake.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル環境

次の内容を MCP クライアントの設定ファイルに追加してください。

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

または、npx を使用する場合（Bun は不要です）：

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

または、Docker を使用する場合：

{
  "mcpServers": {
    "earthquake-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/earthquake-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 以降。
• API キーは不要です。USGS と EMSC のデータは完全に公開されています。

インストール

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

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

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

cd earthquake-mcp-server

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

bun install

設定

すべての設定は、起動時に src/config/server-config.ts の Zod スキーマで検証されます。主な環境変数は次のとおりです。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http	stdio
MCP_HTTP_PORT	HTTP サーバーのポート	3010
MCP_HTTP_ENDPOINT_PATH	MCP サーバーがマウントされる HTTP エンドポイントのパス	/mcp
MCP_PUBLIC_URL	TLS を終端するリバースプロキシ環境で使用する、公開オリジンの上書き値	なし
MCP_SESSION_MODE	HTTP セッション：stateful、stateless、または auto（stateful に解決されます）。createApp() の宣言を上書きします。Docker と .env.example でも stateless に固定されています。	stateless（src/index.ts で宣言）
MCP_AUTH_MODE	認証：none、jwt、または oauth	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）	info
MCP_GC_PRESSURE_INTERVAL_MS	オプトインで有効にする、Bun 専用の強制 GC 圧力ループ（ミリ秒）。継続的な HTTP 負荷のもとでヒープの増加が見られる場合は、60000 をお試しください。	0（無効）
LOGS_DIR	Node.js と Bun でのログファイル保存ディレクトリ	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗したツールの引数と結果を、キー名に基づいて機密情報をマスキングして記録します。自由形式の値に含まれるシークレットはマスキングされません。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	記録する失敗ペイロードごとの UTF-8 バイト上限	16384
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
USGS_BASE_URL	USGS API のベース URL。テストやミラーリングで上書きします。	https://earthquake.usgs.gov
EMSC_BASE_URL	EMSC API のベース URL。テストやミラーリングで上書きします。	https://www.seismicportal.eu
DEFAULT_LIMIT	earthquake_search_events のデフォルト結果数	100
REQUEST_TIMEOUT_MS	試行ごとの HTTP タイムアウト（ミリ秒）。フィードと検索には、共通で 50 秒の合計上限も適用されます。単独のイベント／件数呼び出しには、この試行ごとの値が使用されます。	10000
OTEL_ENABLED	OpenTelemetry を有効にします	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレース（/v1/traces）とメトリクス（/v1/metrics）のベース URL。シグナル固有のエンドポイント変数がある場合は、そちらが優先されます	なし
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	オプトインで有効にする OTLP ログのエンドポイント。そのまま使用され、ベース URL によってログが有効になることはありません	なし

空の値と、値全体が置換されていない ${…} プレースホルダーにはデフォルト値が使用されます。任意の上書き設定については .env.example を参照してください。

サーバーの実行

ローカル開発

• 本番バージョンをビルドして実行する：

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

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

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Docker

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

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

プロジェクト構成

ディレクトリ	用途
src/mcp-server/tools	ツール定義（*.tool.ts）。USGS と EMSC の 4 つのツール。
src/mcp-server/resources	フィード、フィード継続、イベントの各リソース。
src/services/feed-snapshots.ts	ペイロードとメタデータのサイズを制限して管理する、テナント単位のシリアライズ済みフィード保持機能。
src/services/usgs	USGS ComCat サービス — GeoJSON フィード取得機能および FDSN クエリ API クライアント。
src/services/emsc	EMSC SeismicPortal サービス — FDSN イベント検索および件数エンドポイント。
src/config	サーバー固有の環境変数の解析と、Zod による検証。
tests/	src/ の構成に対応するユニットテストと統合テスト。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch を使わないでください。
• ログ記録には ctx.log を、ストレージには ctx.state を使用してください。
• 新しいツールとリソースは、createApp() の配列に登録してください。
• 上流データを検証してドメイン型に正規化し、事実を捏造せず、欠損値はそのまま保持してください。

コントリビューション

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

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。