nws-weather-mcp-server

---

概要

National Weather Service による米国のリアルタイム天気情報です。50 州および米国領土の任意の地点について、天気予報、発令中の警報、現在の気象状況、予報官の解説を確認できます。さらに、気象ゾーンの予報、沿岸・海上警報、観測所の過去 1 週間分の履歴も取得できます。API キーは不要です。

ツール

ツール	説明
nws_get_forecast	座標を指定して、7 日間または時間ごとの予報を取得します。NWS のグリッドを内部で解決します。
nws_search_alerts	地域、地点、ゾーン、現象、重大度、緊急度、確度、ステータスで絞り込んだ発令中の気象警報を取得します。
nws_get_alert	ID を指定して、現在の警報または置き換えられた警報のメッセージを 1 件取得します（保持期間は約 7 日間）。
nws_get_alert_counts	全国、州・領土別または海域別、さらに海洋地域別の発令中の警報件数を取得します。
nws_get_observations	座標（最寄りの観測所）または観測所 ID を指定して、現在の気象状況を取得します。
nws_get_observation_history	観測所の最近の観測情報を新しい順に取得します。NWS が保持する約 7 日分の履歴をページ単位でさかのぼれます。
nws_find_stations	周辺の観測所を距離順に並べ、方位とともに取得します。
nws_list_alert_types	フィルターの設定に利用できる、有効な警報現象タイプ名をすべて取得します。
nws_get_office_discussion	Weather Forecast Office の最新の解説資料（AFD、HWO、ZFP、SPS、FWF）を取得します。インライン表示には大きすぎる資料は、セクションの概要として返されます。
nws_get_zone_forecast	NWS の予報ゾーンにおける期間別のテキスト予報を取得します。

リソース

リソース	説明
nws://alert-types	有効なNWS警報イベント名の静的な一覧です。

リソースに対応していないMCPクライアント向けに、nws_list_alert_types ツールからも利用できます。

機能リファレンス

nws_get_forecast _ツール

• latitude + longitude を指定します。デフォルトでは名前付きの12時間単位の期間を14件（約7日分）返します。また、hourly: true を指定すると、露点と湿度を含む1時間単位の期間を返します。1ページあたり48件で、上流のデータは約156件です。
• nextCursor にはモードが引き継がれるため、時間単位の取得を続ける場合も hourly: true を再送信する必要はありません。
• include_amounts: true を指定すると、各ネイティブの quantitativePrecipitation、snowfallAmount、iceAccumulation の時間区間が precipitationAmounts（layer、uom、validTime と value を含む values）として追加されます。また、別途 amountsUpdateTime も返されます。デフォルトは false です。降水量が必要なカーソルページでは、毎回再指定してください。期間文字列、単位、ゼロ値、null値は変更されません。存在しないレイヤーや利用できない降水量は notice で説明されます。存在するが空のレイヤーでは values: [] が返されます。単位や更新時刻がない場合は null になります。降水量フィードが利用できなくても、予報本体は利用できます。
• グリッドの予報データが最後に更新された時刻を示す updateTime を generatedAt とともに返します。グリッドが24時間以上更新されていない場合は notice で通知されます。
• nws_search_alerts に連携するための forecastZone と county のゾーンコードを返します。
• 海上の座標では marine_forecast_unsupported が返され、NWSが予報グリッドを提供していない陸上地点では no_forecast_grid が返されます。

---

nws_search_alerts _ツール

• 場所のフィルター（area、point、zone、region_type、region）は最大1つまで指定できます。指定しない場合は全国を検索します。event は大文字・小文字を区別せず、一部一致で検索します。status のデフォルトは Actual です（Exercise、System、Test、Draft も指定できます）。
• limit（デフォルトは25）の上限は25です。25を超える値を指定した場合も25件が返され、requestedLimit／effectiveLimit で報告されます。
• nextCursor にはクエリのフィルターとページサイズが引き継がれるため、単独で cursor として渡してください。併せて送信されたフィルターは無視されます。
• 各 affectedZones エントリーにはゾーンの type（forecast／county／fire）が含まれます。references には置き換えられたメッセージが sent の新しい順に記載されます。NWSの管轄外の point では invalid_point が返されます。
• 各警報には、nws_get_office_discussion で使用する発表官署コード（例：RIW）である office、生の vtec 文字列、nwsHeadline、および maxHailSize や maxWindGust などの hazard タグがそのまま含まれます。

---

nws_get_alert _ツール

• alert_id には、nws_search_alerts の警報 id、または任意の警報に含まれる references[].identifier を指定します。置き換えられたメッセージを含め、nws_search_alerts と同じ形式の { alert } を返します。
• 不正なID、不明なID、またはNWSの約7日間の保持期間を過ぎたIDは、いずれも alert_not_found となります。

---

nws_get_alert_counts _ツール

• 入力は不要です。全国の totalAlerts（landAlerts + marineAlerts）に加え、州／準州または海域コードをキーとする areas の件数と、海域（AL、AT、GL、GM、PA、PI）をキーとする regions の件数を返します。いずれも有効な警報があるコードのみを列挙します。
• 件数には Test と Exercise を含むすべてのメッセージステータスが含まれるため、totalAlerts は全国の nws_search_alerts の totalCount（デフォルトの status: Actual）を上回ることがあります。警報は、そのゾーンが含まれる各エリアで1回ずつ数えられるため、areas の合計が totalAlerts を超えることがあります。

---

nws_get_observations _ツール

• 座標を指定して検索すると最寄りの観測所が特定されます。または station_id を直接指定できます。
• すべての測定値を2種類の単位（F／C、mph／km/h、inHg／hPa、mi／km、in／mm）で表示し、気温は小数第1位まで示します。1時間、3時間、6時間の降水量は毎時報告から取得され、0 は微量、null は降水量の報告がないことを示します。観測から2時間以上経過している場合は古いデータであることを notice で通知し、ほとんどの測定値を取得できない観測所には別途警告を表示します。

nws_get_observation_history _tool

• station_id（nws_find_stationsから取得）。start（指定時刻を含む）とend（指定時刻を含まない）は省略可能で、秒とオフセットを含むISO 8601形式の日時を指定します。新しい順に、NWSが保持する約7日分まで取得します
• limit（デフォルトは24）の上限は100です。上限を超える値を指定した場合は100件が返され、requestedLimit／effectiveLimitで報告されます
• 各観測値にはnws_get_observationsの測定フィールドが含まれます。観測所から報告されなかった値はnullになります。不明な観測所を指定するとstation_not_found、不正な期間、またはstartがendより前でない場合はinvalid_time_windowが返されます
• 古い観測値が残っている場合に限りnextCursorが含まれます。NWSは期間内の件数を報告しないため、totalCountはありません

---

nws_find_stations _tool

• latitudeとlongitudeを指定します。limit（デフォルトは10）は省略可能で、上限は50です。上限を超える値を指定した場合は50件が返され、requestedLimit／effectiveLimitで報告されます
• 近い順に返されます。各結果には、nws_get_observationsで使用する観測所ID、距離（km）、方位、ゾーンコード、標高、タイムゾーンが含まれます

---

nws_list_alert_types _tool

• NWS APIが認識するすべてのイベントタイプ（例：「Tornado Warning」「Heat Advisory」）を返します
• nws_search_alertsのeventフィルターに指定できる値を確認するために使用します

---

nws_get_office_discussion _tool

• office：通常、nws_get_forecastがofficeフィールドとして返す3文字のWFOコード（例：シアトルの場合は「SEW」）。product_type：AFD（デフォルト）、HWO、ZFP、SPS、またはFWF（Fire Weather Planning Forecast）
• productTextに加えて、issuanceTime、issuingOffice、productName、productCode、wmoCollectiveIdを返します。content[]には、固定幅の表の列を維持できるよう、プロダクトテキストがtextコードブロックで格納されます。不明なオフィス、または指定したタイプの現在のプロダクトがないオフィスでは、no_productsが返されます
• インラインで表示するには大きすぎるプロダクト（多くのZFPとFWF）では、productTextの代わりにセクションのoutlineが返されます。該当するセクションを取得するには、sections（AFDのセクション名、またはZFP／HWO／SPS／FWFのゾーンコード）を渡します。不明な名前を指定するとunknown_sectionが返されます
• fireタイプの警報ゾーンの予報を取得するには、FWFを使用します。警報のofficeフィールドの値をofficeに指定し、product_type: "FWF"、sections: [<zone code>]を指定します

---

nws_get_zone_forecast _tool

• zone_id：予報ゾーンコード（例：「WAZ315」）。nws_get_forecast（forecastZone）、nws_find_stations（forecastZone列）、nws_search_alerts（type: "forecast"のaffectedZonesエントリーのcode）から取得できます
• 地元の予報担当者による解説文とともに、「Today」「Tonight」「Monday」などの名前付き期間を返します
• 郡（XXC###）と不明なゾーンコードではzone_not_foundが返されます。多くの火災ゾーンコードでも同様です。これらの予報はnws_get_office_discussionで取得するオフィスFWFの該当セグメントに含まれます。火災コードが一般向けゾーンコードでもある場合は、その一般向けゾーンの予報が返されます。テキスト予報のない海上ゾーンではmarine_forecast_unsupported、陸上ゾーンではzone_forecast_unavailableが返されます

---

nws://alert-types _resource

• 有効なNWS警報イベントタイプ名をすべて含む静的リストをapplication/jsonとして返します
• パラメーターはありません。1時間、公開キャッシュされます

機能

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

NWS 固有の機能：

• 必須の User-Agent ヘッダーを自動送信します（NWS_USER_AGENT で設定可能）。ヘッダーがないと NWS は 403 を返します
• /points による座標からグリッドへの自動解決に対応しています。グリッドセルはほとんど変化しないため、1 時間キャッシュされます
• リクエストのタイムアウトに加え、NWS API の一時的な障害に対する再試行とバックオフに対応しています
• 認証不要でアクセスできます。API キーは必要ありません
• ページ分けされた結果に対応しています。次のページを取得するには、返された nextCursor を cursor として渡します（最後のページでは省略されています）

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

• 出典情報 — レスポンスにはオフィスコード、タイムゾーン、ゾーンコードが含まれるため、エージェントは nws_get_office_discussion、nws_get_zone_forecast、nws_search_alerts に連携できます
• 無言ではなくガイダンスを返します — 結果が空、途中で切り詰められている、またはカーソルが末尾を過ぎている場合は、原因と次の手順を示す notice が含まれます
• 型付きのエラー理由（invalid_area_code、no_products、zone_not_found、…）により、呼び出し元は文字列を解析せず、データに基づいて処理を分岐できます
• 出力テキストと一致するように丸めた、2 単位系での測定値（F/C、mph/km/h、inHg/hPa、mi/km、in/mm）

はじめに

公開ホストインスタンス

公開インスタンスは https://nws.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP を提供しており、クライアントごとに設定形式が異なります。

Claude Code の場合：

claude mcp add --transport http nws-weather-mcp-server https://nws.caseyjhand.com/mcp

Cline の場合（cline_mcp_settings.json）：

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

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "nws-weather-mcp-server": {
      "url": "https://nws.caseyjhand.com/mcp"
    }
  }
}

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

セルフホスト／ローカル

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

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

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

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

または、Docker を使う場合：

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

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

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

前提条件

• Node.js v24+ または Bun v1.4+

インストール

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

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

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

cd nws-weather-mcp-server

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

bun install

設定

変数	説明	デフォルト
NWS_USER_AGENT	NWS API リクエスト用の User-Agent。API はこのヘッダーを必須としています。	(nws-weather-mcp-server, ...)
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_HOST	HTTP サーバーのホスト名。	127.0.0.1
MCP_SESSION_MODE	HTTP セッションモード：stateful、stateless、または auto。	stateless
MCP_LOG_LEVEL	ログレベル：debug、info、notice、warning、error。	info

認証、ストレージ、OpenTelemetry のオプションを含む全項目については、.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
  bun run test         # Runs test suite
  

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイント — ツールとリソースを登録します。
src/mcp-server/tools/definitions/	ツール定義（*.tool.ts）。
src/mcp-server/resources/definitions/	リソース定義（*.resource.ts）。
src/services/nws/	NWS API クライアントとレスポンス型。
src/config/	Zod による環境変数の解析と検証。
tests/	src/ の構成に対応する単体テストと統合テスト。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します — ツールのロジックで try/catch を使わないでください
• ドメイン固有のログには ctx.log を、ストレージには ctx.state を使用します
• 新しいツール／リソースは、バレルエクスポートと src/index.ts の createApp() 配列に追加します
• NWS API 呼び出しはラップします：生の JSON を検証 → ドメイン型に正規化 → 出力スキーマを返します。不足しているフィールドを決して捏造しないでください

コントリビューション

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

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE をご覧ください。