noaa-climate-mcp-server

---

概要

NOAA の過去の気象・気候記録を利用できます。Climate Data Online の観測所データ、Storm Events Database、Billion-Dollar Weather and Climate Disasters のデータが含まれます。観測所を検索し、希望する単位で観測データを取得したり、暴風雨による被害や災害の費用を調べたりできます。

ツール

ツール	説明
noaa_climate_list_datasets	利用可能なCDOデータセットを、ID、名前、対象期間とともに一覧表示します
noaa_climate_list_data_categories	データカテゴリのグループ（気温、降水量、風など）を一覧表示します
noaa_climate_list_data_types	データセットまたはカテゴリ別に、具体的な測定項目のラベル（TMAX、TMIN、PRCP、SNOWなど）を一覧表示します
noaa_climate_list_location_categories	場所の検索範囲を定める12種類の場所カテゴリを一覧表示します
noaa_climate_find_locations	カテゴリ（州、都市、郡、郵便番号、気候地域）で地理的な場所を検索します。名前で絞り込むこともできます
noaa_climate_find_stations	場所、境界ボックス、データセット、データタイプで気象観測所を検索します
noaa_climate_get_station	IDを指定して、単一の観測所の全メタデータを取得します
noaa_climate_fetch_data	データセットと日付範囲を指定して、過去の観測記録を取得します
noaa_climate_search_storm_events	NCEI Storm Events Databaseを1年分検索します。竜巻、雹、洪水、ハリケーンについて、被害、死傷者、概要を取得します
noaa_climate_get_billion_dollar_disasters	NOAAの廃止済み1980～2024年「Billion-Dollar Weather and Climate Disasters」アーカイブを照会します。災害ごとのCPI調整済み費用と死者数、または災害クラス別の年ごとの合計を取得します

リソース

リソース	説明
noaa://datasets	IDと対象期間を含む、すべてのCDOデータセット。データを照会する前にエージェントに前提情報を与えるためのコンテキストとして注入できます
noaa://stations/{stationId}	IDで指定した観測所のメタデータ。名前、座標、標高、データの対象期間を含みます

機能リファレンス

noaa_climate_list_datasets _ツール

• 必須の入力はありません。データタイプ、場所、観測所、日付範囲で任意に絞り込めます。limit は1～1000（デフォルトは25）、offset も指定できます。id、name、mindate、maxdate、datacoverage で並べ替えられます
• 各データセットのID、名前、日付範囲を返します。GHCND（日次、1763年～現在）、GSOM（月次）、GSOY（年次）、NORMAL_DLY/MLY/ANN/HLY（1981～2010年の平年値）が含まれます
• 日付フィルターでは、対象期間が指定範囲と重なるかを判定します。指定された各境界について、maxdate >= startDate および mindate <= endDate が条件です。その他のフィルターに一致するカタログ全体を取得してから、フィルタリングとページネーションを行います。合計件数は、フィルタリング後の表示範囲を示します。

---

noaa_climate_list_data_categories _ツール

• データセット、場所、観測所、日付範囲で任意に絞り込めます。limit は1～1000（デフォルトは25）、offset も指定できます。id または name で並べ替えられます
• 42種類の測定カテゴリ（気温、降水量、風、気圧、日照など）を返します。カテゴリのIDを datacategoryId として指定すると、noaa_climate_list_data_types の結果を絞り込めます

---

noaa_climate_list_data_types _ツール

• datasetId（例：GHCND）または datacategoryId（例：TEMP）で絞り込みます。limit は1～1000（デフォルトは25）、offset も指定できます
• noaa_climate_fetch_data が受け付けるデータタイプIDを返します。一般的なGHCNDのタイプは TMAX、TMIN、PRCP、SNOW、SNWD、AWND です。CDOに情報がある場合は、カバレッジと日付範囲も返します

---

noaa_climate_list_location_categories _ツール

• ページネーションと並べ替えのみ指定できます。limit は1～1000（デフォルトは25）、offset も指定でき、id または name で並べ替えられます
• noaa_climate_find_locations が locationCategoryId として受け付ける12種類のカテゴリIDを返します。CITY、ST、CNTY、CNTRY、ZIP、US_TERR、CLIM_REG、CLIM_DIV、HYD_ACC、HYD_CAT、HYD_REG、HYD_SUB が含まれます

---

noaa_climate_find_locations _ツール

• locationCategoryId で検索範囲を絞り込みます（例：ST は全51州を返します）。datasetId、datacategoryId、日付範囲の各フィルターは任意です。limit は1～1000（デフォルトは25）で、offset を指定できます。
• noaa_climate_find_stations と noaa_climate_fetch_data に渡す場所 ID（FIPS:37、CITY:US530018、ZIP:98101）を返します。
• nameContains を指定すると、最大4,000か所の1つのカテゴリ内（ZIP 以外のすべてのカテゴリ）で、大文字と小文字を区別しない名前の一致条件を追加します。カテゴリを指定しない場合は name_filter_requires_category、上限を超えるカテゴリでは name_filter_category_too_large として失敗します。

---

noaa_climate_find_stations _ツール

• locationId、extent（緯度・経度の境界ボックス）、datasetId、datatypeId（配列）、日付範囲で絞り込みます。limit は1～1000（デフォルトは25）で、offset を指定できます。
• extent は minLat,minLon,maxLat,maxLon の形式です。有限の符号付き10進数または指数表記の数値を4つ指定し、前後に空白を含めることができます。緯度は±90以内、経度は±180以内です。座標が同じ場合も有効です。軸が逆の場合は一致なしとなり、日付変更線をまたぐ処理は行われず、そのまま転送されます。
• ステーション ID（GHCND:USW00024233、COOP:010008）、名称、座標、標高、データ対象期間を返します。これらの ID は noaa_climate_fetch_data の stationId として使用します。

---

noaa_climate_get_station _ツール

• 必須入力は stationId のみです。noaa_climate_find_stations から取得します。noaa://stations/{stationId} リソースのツール形式です。
• 名称、座標、標高、データ対象期間の全期間を返します。形式が正しい ID に対応する情報が見つからない場合は、not_found として失敗します。

---

noaa_climate_fetch_data _ツール

• datasetId、startDate、endDate が必須です。stationId、locationId、datatypeId 配列は任意です。期間の上限は、GHCND、PRECIP_15、PRECIP_HLY、NORMAL_DLY、NORMAL_HLY、NEXRAD2、NEXRAD3では1年、GSOM、GSOY、NORMAL_MLY、NORMAL_ANNでは10年です。NORMAL_* データセットでは、startDate=2010-01-01／endDate=2010-12-31 を指定します。
• フラットな { date, datatype, station, value, attributes } レコードと、クエリ内容を反映した effectiveQuery を返します。date_range_exceeded には、CDO が受け付ける最新の maxEndDate が示されます。
• units: "metric" または "standard" の指定を強く推奨します。指定しない場合、GHCND の値は単位の10分の1を表す整数のままです（例：TMAX=256 は25.6°C）。

---

noaa_climate_search_storm_events _ツール

• トークンは不要です。year で1つのエクスポートを選択します（1950年から現在の部分年まで）。episodeId（返されたイベントに含まれる正確な数字文字列。前後の空白は削除され、空欄は未指定として扱われ、先頭のゼロは有効です）、state（NCEI の正式名称。例："FLORIDA"）、eventType、month、startDate／endDate、minDamageInUsd で絞り込みます。ページ上限は100で、デフォルトは50です。offset を指定できます。
• 任意の startDate／endDate には、実在する YYYY-MM-DD 日付を指定します。損害額の集計、合計値の計算、ページ分割の前に、指定した日付範囲とイベント期間が重なるもの（両端を含む）を照合します。開始日のみ、終了日のみ、同じ日付、年をまたぐ期間を指定できます。エクスポートの選択に使われるのは year のみです。日付範囲を指定すると、開始日または終了日が欠落、不正、あるいは逆転しているソース行は除外されます。日付範囲を指定しない場合、これらの行も表示されます。appliedDateRange は両方のサーフェスで指定された範囲を反映します。リクエストの日付が逆転している場合、ダウンロード前に invalid_date_range として失敗します。
• 個別のエピソード説明は episodeNarratives に1回だけ表示され、イベントからは episodeNarrativeRef で参照されます。個々の eventNarrative テキストは各イベントに残ります。描画される説明では、句読点と改行がそのまま保持されます。任意のローカル ISO 形式の beginDate／endDate 値は、変更されない NCEI の日時・タイムゾーンフィールドと併せて、CDO の日付フィルターに使用できます。
• 損害額は、桁を表す接尾辞付きの文字列（"1.20M"）と、解析済みの金額として返されます。NCEI が損害額を報告していない場合、ゼロではなく省略されます。一致する結果がない場合、応答には、その年のエクスポートに含まれるイベントタイプと州が示されます。
• NCEI がその年のファイルを公開していない場合は year_unavailable、ダウンロードしたファイルが想定されるテーブル形式でない場合は malformed_export として失敗します。

---

noaa_climate_get_billion_dollar_disasters _ツール

• デフォルトでは個別の災害を返します。summary=true を指定すると、災害クラス別の年ごとの件数とコストを返します。startYear／endYear、disasterType（7種類のNCEIクラスのいずれか）、minCostInUsd、state（2文字の郵便略号）で絞り込めます。limit は1～100（デフォルトは50）で、offset も指定できます。
• エクスポートで宣言されている単位にかかわらず、すべてのコストは米ドルの整数で返されます（宣言された単位は declaredCostUnit として含まれます）。state の範囲を指定した場合、全国のコスト（costBasis: "national"）と、年ごとに区分された costRangeInUsd が返されます。
• NOAAは2024年をもってこのプロダクトを終了しました。1980～2024年のアーカイブは引き続き利用できますが、それ以降の年が追加されることはありません。coveredYears には、選択されたエクスポートに実際に含まれる期間が示されます。成功したレスポンスには、制限値の調整やページングに関する案内とともに、このアーカイブに関する注意事項が含まれます。
• CPI調整後のコストには、アーカイブされたエクスポートの調整がそのまま反映されます。サーバーは現在の価格に基づいて再計算したり、CPIの基準年を推定したりしません。

---

noaa://datasets _リソース

• すべてのCDOデータセットを application/json 形式で返します（ID、名称、対象期間）。
• フィルターなしで高い上限値を指定した noaa_climate_list_datasets と同等です。注入可能で、取得は行いません。

---

noaa://stations/{stationId} _リソース

• noaa_climate_find_stations で取得した stationId を指定します。noaa_climate_get_station のリソース形式です。
• 観測所のメタデータを返します。形式が正しいIDに該当するデータがない場合は、not_found エラーになります。

機能

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

NOAA固有の機能：

• CDO API v2の全機能を網羅しています。データセット、データカテゴリ、データタイプ、場所、観測所、観測データに加え、トークン不要のNCEI一括CSVデータセットを2種類（悪天候イベント（Storm Events Database）と、10億ドル規模の災害コスト）提供します。
• API呼び出し前に、データセットごとにクライアント側で日付範囲を検証し、正確な上流側の制限値を呼び出し元に報告します。
• 検索日付の範囲では、リクエスト前に startDate > endDate を拒否し、validation_error と値を入れ替えるよう促すヒントを返します。同じ日付や片方のみの指定は有効です。YYYYMMDD 形式、ゼロ埋めされていないダッシュ区切りの日付、および対応する秒精度の日時形式は、比較用に正規化されます。
• CDOの units パラメーターで単位を正規化し、単位の10分の1を整数で表す値と混同しないようにします。
• CDOが返した拒否メッセージを取得して提示します。日付範囲が長すぎる場合、不正な日付の場合、パラメーターが不足している場合には、ステータス行だけでなく、CDOが示した理由を報告します。
• 10億ドル規模の災害コストは、各NCEIエクスポートの冒頭で宣言されている単位から米ドルの整数に変換されます。単位はエクスポートによって異なるためです。

エージェントに適した出力：

• すべてのリストツールと検索ツールで、ページ分割された結果を返します。入力と返却メタデータの offset は0始まりです。ローカルでフィルタリングされたデータセットと場所の一覧では、フィルタリング後の結果からメタデータを生成します。それ以外のCDOページでは、上流のメタデータが存在しない場合、そのまま保持します。座標と対象期間の精度は上流の値を維持し、対象期間のテキストには0～1の範囲を示す未加工の小数を使用します。
• 正の整数の取得件数上限は、ページ上限値に調整されます。CDOでは1000、Storm Eventsと10億ドル規模の災害では100です。空のページや結果の枯渇に関する案内とともに、リクエストされた上限値と適用された上限値を通知します。offset を進める際は、適用された上限値を使用してください。上限値の調整はログに記録され、noaa.pagination.limit_clamped としてカウントされます。
• 観測所、場所、データセットのIDはツール間で自然に引き継がれます。場所を検索し、その場所にある観測所を検索して、それらの観測所のデータを取得できます。
• 型付きの reason コードと復旧のヒントを含む、構造化されたエラー契約を備えています。エージェントは文字列を解析せず、データに基づいて処理を分岐できます。
• 損害額とコストのフィールドでは、上流データの欠落を正直に扱います。NCEIの数値が報告されていない場合、確定したゼロとしてではなく、値を省略します。

はじめに

公開ホストインスタンス

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

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

セルフホスト／ローカル

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

{
  "mcpServers": {
    "noaa-climate-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/noaa-climate-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NOAA_CDO_TOKEN": "your-token-here"
      }
    }
  }
}

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

{
  "mcpServers": {
    "noaa-climate-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/noaa-climate-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NOAA_CDO_TOKEN": "your-token-here"
      }
    }
  }
}

または、Docker を使用します。

{
  "mcpServers": {
    "noaa-climate-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "NOAA_CDO_TOKEN=your-token-here", "ghcr.io/cyanheads/noaa-climate-mcp-server:latest"]
    }
  }
}

Streamable HTTP を使用するには、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NOAA_CDO_TOKEN=your-token-here bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js ≥24.0.0）。
• 無料の NOAA CDO API token — CDO リクエストに必要です。Storm Events と Billion-Dollar Disasters ではトークンは不要です。

インストール

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

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

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

cd noaa-climate-mcp-server

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

bun install

4. 環境を設定します。

cp .env.example .env
# edit .env and set required vars

設定

サーバー固有の設定には、src/config/server-config.ts の Zod スキーマを使用します。ページ上限ポリシーは起動時に検証され、CDO トークンは CDO リクエストの実行時に必要となります。主な環境変数は次のとおりです。

変数	説明	デフォルト
NOAA_CDO_TOKEN	CDO に必須です。 ncdc.noaa.gov/cdo-web/token で無料取得できます。2 つの一括コーパスではトークンは不要です	—
NOAA_CLAMP_LIMITS	true にすると、正の整数で指定された読み取り上限をページ上限に制限します。false にすると、上限を超えた場合にスキーマによる拒否が再び有効になります。受け付けるのは完全一致の文字列 true と false のみです。それ以外の空でない値では起動に失敗します。この設定を変更した後は再起動してください。	true
MCP_TRANSPORT_TYPE	トランスポート：stdio または http	stdio
MCP_HTTP_PORT	HTTP サーバーのポート	3010
MCP_HTTP_ENDPOINT_PATH	MCP サーバーをマウントする HTTP エンドポイントのパス	/mcp
MCP_SESSION_MODE	HTTP セッションの動作モード：stateful、stateless、auto。デフォルトは stateless です。ハンドラーの実行途中で呼び出し元に入力を求めるツールはありません	stateless
MCP_PUBLIC_URL	TLS を終端するリバースプロキシを使用したデプロイでの、公開オリジンの上書き設定	なし
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（無効）
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	OpenTelemetry を有効にします	false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP ベース URL。トレースは /v1/traces に、メトリクスは /v1/metrics に送信されます。この値を設定しない場合、何もエクスポートされません	なし
LOG_TOOL_FAILURE_PAYLOADS	失敗した各ツール呼び出しの引数と結果を、キー名による秘匿化を行い、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）を上限としてログに記録します。自由形式の値に含まれるシークレットは秘匿化されません。	false

オプションの上書き設定の一覧は .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
  bun run test:live # Opt-in: resolves every documented example identifier against the live CDO API
  

Docker

docker build -t noaa-climate-mcp-server .
docker run --rm -e NOAA_CDO_TOKEN=your-token-here -p 3010:3010 noaa-climate-mcp-server

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

プロジェクト構成

ディレクトリ	目的
src/mcp-server/tools	ツール定義（*.tool.ts）。データセット、場所、観測所、観測データ、暴風雨イベント、災害コストに関する10個のツールです。
src/mcp-server/resources	リソース定義。データセットカタログと観測所のメタデータリソースです。
src/services/cdo	リトライ、バックオフ、camelCase→小文字のパラメーター変換、CDO 独自の拒否メッセージの復元に対応する CDO HTTP クライアントです。
src/services/csv	2つの NCEI 一括 CSV コーパスで共有される、RFC 4180 対応のインクリメンタル CSV リーダーです。
src/services/storm-events	NCEI Storm Events 一括 CSV クライアントです。ファイル名の検出、ストリーミング展開、損害額の解析を行います。
src/services/billion-dollar-disasters	NCEI Billion-Dollar Disasters クライアントです。宣言された単位の解決と、米ドルの整数額への換算を行います。
src/config	Zod を使用した、サーバー固有の環境変数の解析と検証です。
tests/	src/ の構成を反映した、単体テストと統合テストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークがキャッチします。ツールのロジックで try/catch を使用しないでください
• ログには ctx.log、ストレージには ctx.state を使用してください
• 新しいツールとリソースは、createApp() の配列に登録してください
• 外部 API 呼び出しは、生データの検証 → ドメイン型への正規化 → 出力スキーマの返却、の順でラップしてください。不足しているフィールドを捏造してはいけません

コントリビューション

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

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License のもとでライセンスされています。詳細については、LICENSE ファイルを参照してください。