aviation-weather-mcp-server

---

概要

NWS Aviation Weather Center の航空気象情報を提供します。METAR、TAF、PIREPs、国内／国際 SIGMET、Center Weather Advisories を取得できます。観測所の検索、現在の気象状況や予報の取得、パイロットレポートや危険気象情報の取得が可能です。AIRMET は提供されません。

ツール

ツール	説明
aviation_find_stations	識別子、バウンディングボックス、または米国の州を指定して空港と気象観測所を特定します。ICAO/IATA/FAA ID、座標、標高、利用可能なデータの種類を返します。
aviation_get_metar	指定した空港の現在の気象観測（METAR）を取得するか、バウンディングボックス内のすべての報告観測所を調査します。デコード済みの風、視程、雲底、現在の天気、気温／露点温度、高度計規正値、雲層、飛行カテゴリー（VFR/MVFR/IFR/LIFR）、および生のMETAR文字列を返します。
aviation_get_taf	1つ以上の空港の飛行場予報（TAF）を取得します。有効時刻、地上風、低層ウィンドシアー、視程、デコード済みの天気、雲層、予報対象となる視程障害の鉛直視程を含む各予報期間と、生のTAF文字列を返します。
aviation_get_pireps	空港付近またはバウンディングボックス内の最近のパイロットレポートを取得します。高度、航空機の種類、強度、外気温、高高度の風、飛行中の天気、生のPIREP文字列とともに、デコード済みの乱気流、着氷、雲の報告を返します。
aviation_get_advisories	国内／国際SIGMETおよびセンター気象勧告を取得します。対象範囲、ハザード、深刻度、高度、有効期間、移動、複数部分のジオメトリ、元の速報を返します。省略された情報はnullのままです。

プロンプト

プロンプト	説明
aviation_preflight_brief	上記のツールを順番に呼び出して、飛行のための出発前気象ブリーフィングを構成し、気象リスクの概要をまとめます。

---

機能リファレンス

aviation_find_stations _tool

• 識別子で1つ以上の観測所を検索します（1回の呼び出しにつき最大20件）。検索ではレジストリ独自のIDと照合します。空港の場合、このIDは4文字のICAO ID（例：KSEA、K0S9）です。3文字のIATAコードでは検索できませんが、利用可能な場合は各レコードにIATA/FAAの別名が含まれます
• 地理的なバウンディングボックス内の観測所を検索するか、2文字のUSPSコードで米国の50州またはDCの観測所を一覧表示します
• data_types（METAR、TAFなど）を返すため、エージェントは問い合わせる前に利用可能なデータを確認できます
• 各結果には、上流の400行上限によって結果が切り詰められたかどうかが示されます。limit（1～400）を指定すると、bboxまたはstate検索で返される観測所数に上限を設定できます。結果はICAO識別子の昇順で並び、識別子のない観測所は最後に表示されます。station_idsと併用すると拒否されます。このモードでは対象の集合がすでに指定されているためです。limitを指定せずにエリア検索を行い、130件を超える観測所が見つかった場合は、その旨と上限を変更する方法が示されます。limitを省略しても、該当するすべての観測所が返されます
• ID検索では、解決できなかった識別子がすべて示されます。検索できない3文字のIATAコードと、レジストリに登録されていない識別子は区別されます
• IDの前後の空白はバッチエラーにならず、削除されます。拒否されるのは空の値または空白のみの値だけです

---

aviation_get_metar _ツール

• 名称指定の空港には station_ids（1回につき1〜10件 — ASCIIの英字または数字4文字。大文字・小文字は区別せず、大文字に正規化されるため、ksea と K0S9 のどちらも使用できます）、またはエリア内のすべての観測所を調査するには bbox を指定します。両者は同時に指定できません
• hours（1〜12）は取得対象期間であり、行数の上限ではありません。station_ids を指定した場合は期間内のすべての観測が返され、bbox を指定した場合は観測所ごとの最新の観測が返されます
• flight_category（例：["IFR", "LIFR"]）を指定すると、bbox 調査の対象を該当カテゴリの観測所に絞り込めます。各観測所の最新の観測に基づいて判定され、limit より前に適用されます。絞り込み前の調査件数も示されます。AWCがカテゴリを判定できない観測所は一致せず、絞り込み後に結果が空になる場合は、その旨が示されます。station_ids と同時に指定するとエラーになります
• bbox 調査では、上流の400行の上限に達したかどうかが示されます。また、hours: 1 より大きい場合は、最初に調整する項目として hours が案内されます。期間を広げると、観測所数ではなく同じ観測所の繰り返し観測に上限を消費するためです。limit（1〜400）を指定すると返される観測所数を制限し、観測所IDの昇順で並べます。station_ids と同時に指定するとエラーになります。limit を指定せずに40を超える観測所が返される場合は、その旨と調整項目が案内されます。limit を省略しても、すべての観測所が返されます
• AWC APIから直接返される飛行カテゴリー（VFR/MVFR/IFR/LIFR）。生のMETAR文字列に加え、風、視程、現在天気、雲層をデコードします
• シーリングは高度と種類の両方を報告します（測定値、または視界不良時の鉛直視程に対する不定値）。clouds が空の場合も、sky_condition によって晴天の報告があったのか、報告がなかったのかを区別できます
• metar_type で、通常の METAR と特別観測の SPECI を区別できます
• 各バッチでは、要求した観測所のうちどれが返されたかを報告し、欠落したIDとその際の対処方法を示します

---

aviation_get_taf _ツール

• 1回につきICAO観測所IDを1〜4件受け付けます。ASCIIの英字または数字4文字で、大文字・小文字は区別せず、大文字に正規化されます
• 変化タイプ（FM、TEMPO、BECMG）と確率を含む構造化された予報期間。生のグループに加え、天気をグループごとにデコードします
• 予報上の視界不良は層を保持し、その層に対する鉛直視程も含めて示されるため、晴天とは解釈されません。sky_condition によって、変更のない期間と晴天の報告があった期間を区別できます
• 上流のデコーダーがデコードできなかったテキスト（4つ目の雲層など）は、破棄せず、期間ごとに not_decoded で示されます
• 低層ウィンドシア（WS020/20040KT）を、シア層の上端とその高度での予報風にデコードします
• 時刻の比較に使用できる、ISO 8601形式の valid_from / valid_to
• 各バッチでは、要求した観測所のうちどれが返されたかを報告し、欠落したIDとその際の対処方法を示します

aviation_get_pireps _ツール

• 放射状検索には station_id（大文字・小文字を問わない4文字のASCII英数字。大文字に正規化）と distance_nm（10～500 nm。省略時は100）を指定するか、エリア検索には bbox を指定します。これらは相互に排他的です。AWC が検索中心として認識しない station_id を指定すると、aviation_find_stations または bbox を案内する型付きエラーが返されます
• altitude_min_ft / altitude_max_ft は、MSL 基準の巡航高度帯（0～60000 ft）で絞り込みます（最小値は最大値以下である必要があります）。いずれかの境界を設定すると、高度不明の報告は除外されます
• min_intensity（lgt / mod / sev）を指定すると、その強度以上の乱気流または着氷のレイヤーを含む報告に絞り込まれます。一致した報告には、より弱いレイヤーも引き続き含まれます
• 乱気流と着氷の配列には、報告ごとに最大2つのレイヤーが含まれます。氷について言及していない報告に対して API が合成した着氷レイヤーは除外されます
• PIREP と AIREP の両方について、外気温（temp_c）、高高度の風（wind）、および生のグループと併記してデコードされた /WX 飛行気象情報（weather）を返します。風向は報告されたまま出力され、変換されません。PIREP の /WV の風向は、真北基準の METAR および TAF の風向とは異なり、磁北基準です
• すべての結果で、上流の400行上限によって結果が切り詰められたかどうかが示され、その呼び出しで使用可能な絞り込み手段のみが示されます。また、limit（1～400）で返される報告数を指定でき、結果は新しい順に並びます。limit を指定せずに50件を超える報告がある場合は、その旨と利用可能な絞り込み手段が示されます。limit を省略しても、一致する報告はすべて返されます
• PIREP は本質的にまばらです。報告がないからといって、気象が穏やかであるとは限りません

---

aviation_get_advisories _ツール

• advisory_type：sigmet（国内）、isigmet（国際。海洋上を含む）、cwa（センター気象勧告）、または all（デフォルト。3種類の独立したプロダクトすべて）
• hazard は上流で適用されます。国内では CONVECTIVE、TURBULENCE、ICING、IFR、国際では TS、TURBULENCE、ICING、MTW、DS、SS、TC、VA、CWA では TS、TURBULENCE、ICING、IFR、PCPN、UNK に対応しています。対応しないソースは not_applicable となり、対応するソースがない選択は拒否されます
• coverage では、選択した各ソースが ok、failed、not_applicable のいずれかで示され、デコード済みの図示数は読み取り可能なソースについてのみ示されます。partial は、ソースの失敗または読み取り不能な行のスキップを示します。独立した正常なプロダクトは、別のプロダクトの失敗後も利用できます。適用対象のプロダクトがすべて失敗した場合はエラーになります。並行する勧告の読み取りと再試行には、1つの45秒の期限が適用されます。呼び出し元がキャンセルすると、すべての処理が中止されます
• bbox では、正確なポリゴン交差ではなく、日付変更線をまたぐ場合も含め、各ジオメトリ部分の境界エンベロープが使用されます。入力の順序は維持されます（minLat <= maxLat、minLon <= maxLon）。bbox を指定した場合、drawn はプロダクトとハザードによる選択後の行数、matched は地理的に一致した行数、returned は limit 適用後の行数を表し、unlocated はデコード済みジオメトリのない行数を別途示します
• limit は省略可能で、デフォルト値はありません。省略すると、利用可能な一致結果がすべて返されます。明示的に指定すると、ソース、発行者、シリーズ、有効期間の順に並べ替えられ、total / returned / truncated が報告されます。また、省略するか値を増やして、除外された一致結果を取得する方法が説明されます
• 発行者、シリーズ、ハザード、有効期間、生テキストが欠落している場合は null のままです。geometry.parts は、ソース本来の kind（null を含む）とともに、個別のリングや線を保持します。互換性のための polygon は、マルチパート、線、またはジオメトリがない場合に null になります。国内の数値の重要度と移動情報は変更されません。国際の移動情報では direction_text とデコード済みのノット値が保持されます。CWA の重要度と移動情報は null のままで、速報テキストから高度が推測されることはありません
• 元の速報は、空行や埋め込みバッククォートを保持し、安全なコードフェンス内に表示されます。結果が空の場合、読み取り可能なソースと絞り込み段階が示されます。利用できないソースを、気象が良好であることの根拠として扱うことはありません
• AIRMET は提供されません。AIRMET（または MTN OBSCN / SURFACE WIND / LLWS）のリクエストは、AIRMET プロダクトを分けて指定するよう案内して拒否されます

---

aviation_preflight_brief _{プロンプト}

• 引数：departure_icao と destination_icao は必須です。alternates（カンマ区切りの ICAO）、departure_time（ISO 8601 UTC）、cruise_altitude（フィート MSL）、route_waypoints（セミコロン区切りの lat,lon ペア）は任意です
• すべての ICAO 引数には、大文字・小文字を問わず ASCII の英字または数字 4 文字を指定でき、ID は大文字に変換されます。IATA/FAA コードの場合は、state または bbox を指定して aviation_find_stations を使い、ICAO ID を検索してください。コードのマッピングは推測されません。直接指定する ID の前後には空白を付けられませんが、カンマ区切りの代替空港では空白を使用できます
• aviation_get_metar、aviation_get_taf、aviation_get_pireps、aviation_get_advisories を順番に呼び出し、各ツールの 1 回あたりの地点数上限に合わせて分割します
• departure_time は、ブリーフィングで参照する TAF の予報期間を選択します。cruise_altitude は PIREP の検索範囲を ±3,000 ft の高度帯に限定します。route_waypoints は、各辺を 1°広げた勧告情報の bbox になります
• 3 つのうちいずれかを省略してもブリーフィングを生成し、実施できなかった評価を明記します
• 気象リスクを報告しますが、飛行可否の推奨は行いません。その判断には、パイロット、航空機、運航上の最低基準に関する、このサーバーが保持していない情報が必要です

---

機能

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

航空気象に特化した機能：

• API キー不要 — 認証は不要で、すべてのデータは公開されている AWC Data API から取得します
• キー不要の公開エンドポイントに対する再試行と指数バックオフを備えた単一サービス（aviation-weather-service）
• エージェントが両方のレイヤーを利用できるよう、デコード済みフィールドとともに生のコード文字列（raw_metar、raw_taf、raw_pirep、raw_text）を提供します
• 州から bbox へのテーブルにより、AWC API がネイティブにサポートしていない米国の州単位での地点検索が可能です
• サーバーレベルの instructions フィールドにより、「公式ブリーフィングではありません」という安全上の免責事項を、initialize 時にすべてのクライアントに提示します

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

• 判別可能な出力 — 飛行カテゴリー（VFR/MVFR/IFR/LIFR）を型付き文字列フィールドとして提供するため、エージェントは天井高や視程を解析せずに分岐できます
• 構造化されたエラー契約 — 型付きの reason フィールドと、復旧のヒント（例：「aviation_find_stations で ICAO ID を確認してください」）を提供します
• 部分結果の照合 — バッチツールは requested / returned / missing / partial フィールドを報告するため、件数の少ないバッチを網羅的な結果と誤認することはありません
• ワークフローの順序 — aviation_preflight_brief プロンプトは、正しい METAR → TAF → PIREPs → advisories の順序を定め、各ステップをツールの地点数上限に合わせて分割し、実施できなかった評価を明記します

---

はじめに

公開ホストインスタンス

https://aviation-weather.caseyjhand.com/mcp で、公開ホストインスタンスを利用できます。MCP クライアントの設定に追加してください。

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

セルフホスト / ローカル

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

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

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

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

または Docker を使用します。

{
  "mcpServers": {
    "aviation-weather": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/aviation-weather-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 キーは不要です — AWC Data API は完全に公開されており、キーは必要ありません。

インストール

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

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

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

cd aviation-weather-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env if you need to override AWC_BASE_URL or AWC_TIMEOUT_MS

---

設定

変数	説明	デフォルト
AWC_BASE_URL	NWS AWC Data API のベース URL です。	https://aviationweather.gov/api/data
AWC_TIMEOUT_MS	リクエストごとのタイムアウト（ミリ秒単位、1000～60000）です。	10000
MCP_TRANSPORT_TYPE	トランスポート：stdio または http です。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションの処理方法：auto（stateful に解決されます）、stateful、または stateless です。コードではサーバーに stateless を指定しています。このサーバーのツールは、複数回の往復を要する入力を必要としないためです。提供される .env.example と Docker イメージでも同じ値が設定されています。この値を設定すると、コードでの指定が上書きされます。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth です。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
OTEL_ENABLED	OpenTelemetry instrumentation を有効にします。	false

オプションで上書きできる設定の一覧は .env.example を参照してください。

---

サーバーの実行

ローカル開発

• ビルドして実行：

  bun run rebuild
  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 aviation-weather-mcp-server .
docker run --rm -p 3010:3010 aviation-weather-mcp-server

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

---

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() エントリーポイントです。ツール／プロンプトを登録し、サービスを初期化します。
src/config	サーバー固有の環境変数（AWC_BASE_URL、AWC_TIMEOUT_MS）を解析します。
src/services/aviation-weather	AWC Data API クライアントです。HTTP 取得、指数バックオフによる再試行、レスポンスの正規化を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）です。
src/mcp-server/prompts	プロンプト定義（*.prompt.ts）です。
tests/	src/ の構成に対応するユニットテストと統合テストです。

---

開発ガイド

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

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

正式な出発前ブリーフィングではありません。 AWC のデータは情報提供のみを目的としています。実際の飛行計画には、認可された情報源（例：Leidos/1800wxbrief.com）が必要です。このサーバーは、すべての initialize リクエストで送信される instructions フィールドを通じて、この免責事項を提示します。

---

コントリビュート

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

bun run devcheck
bun run test

---

ライセンス

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