noaa-spaceweather-mcp-server

---

概要

NOAA の Space Weather Prediction Center が提供する宇宙天気情報を取得できます。地磁気嵐、Kp 指数、オーロラ予報、太陽風、太陽活動、発令中の警報に対応しています。現在の状況を確認したり、現在地でオーロラが見えるかを調べたり、太陽風の時系列データを取得したりできます。

ツール

ツール	説明
noaa_spaceweather_get_conditions	現在の宇宙天気の概要：昨日、今日、3日間予報のNOAA R/S/Gストームスケール、最新のKp、平易な言葉による状況の要約、および任意で予報の根拠を説明するSWPCの予報解説
noaa_spaceweather_get_kp_index	惑星K指数（0–9）— Gスケール相当値とオーロラ緯度のガイダンスを含む、最近の観測値（3時間ごと）、および3日間予報
noaa_spaceweather_get_aurora_forecast	OVATIONモデルによるオーロラ予報：全球確率グリッド、座標を指定した場合の任意の地点検索（昼光を考慮した可否判定と極方向の見通しの読み取り値を含む）
noaa_spaceweather_get_solar_wind	稼働中のL1宇宙機によるリアルタイムの太陽風：速度、陽子密度、温度、重要なBz成分と、対象時間帯で最も南向きだった値 — 現在の地磁気条件が生じている理由を説明
noaa_spaceweather_get_solar_activity	太陽フレアの状況：ピーククラスとRスケールレベルを含む個別のフレアイベント、GOES X線フラックス、日次F10.7 cm電波フラックス、フレアクラスの3日間確率、同日フレア件数と翌日確率を含む活動中の太陽領域、および太陽放射線ストームレベル
noaa_spaceweather_get_alerts	有効なSWPCのアラート、監視情報、警報 — プロダクトタイプ、重大度、発行時刻、有効期間、全文を含む構造化レコード

機能リファレンス

noaa_spaceweather_get_conditions _ツール

• 入力は include_discussion（bool、デフォルトはfalse）のみです。1回の呼び出しで noaa-scales.json と noaa-planetary-k-index.json のフィードを組み合わせ、解説がリクエストされた場合は discussion.txt プロダクトも取得します
• 現在のKpとそのGスケール相当値、オーロラ緯度のガイダンス、今日の観測済みR/S/Gレベル、yesterday（前日のUTCの評価済みレベル。フィードにデータがない場合はnull）、および今日から始まるSWPCの3日間予報を返します — 予報のRとSはレベルではなく確率を示し、レベルがnullの場合はレベル0の予報があったという意味ではなく、予報されていないことを示します
• include_discussion を指定すると、予報担当者が作成したForecast Discussionをトピックセクション（Solar Activity、Energetic Particle、Solar Wind、Geospace）に分けて返します。各セクションには24時間の概要と3日間予報のテキストが含まれます

---

noaa_spaceweather_get_kp_index _ツール

• window_days（1–7、デフォルトは1）で観測系列の範囲を指定し、observedCount で一致した観測値の件数を示します。予報は常に、SWPCの今後3日間の全系列（estimated／predicted 行）です
• 各レコードにはKp、そのGレベルとラベル、オーロラ緯度のガイダンスが含まれます。GレベルはSWPCのマイナス3分の1刻みのバンド下限に従います — G1はKp 4.67（5−）から始まり、G5となるのはKp 9のみです

---

noaa_spaceweather_get_aurora_forecast _ツール

• latitude／longitude（WGS84）は省略可能ですが、指定する場合は両方が必要です — 片方だけ指定すると invalid_coordinates エラーになります。指定しない場合、呼び出しはグリッドポイント数、全球のピーク確率、ピーク地域のメタデータのみを返します
• 座標を指定すると、localLookup に最寄りの1°グリッドの確率、地磁気緯度、その地点で必要な最小KpとGレベル、予報時刻の太陽高度と darkness 状態（day、civil_twilight、nautical_twilight、dark）、極方向1,000 km以内で最も高い値（horizonMaxPercent、horizonMaxLatitude、horizonDistanceKm）、および可否を示す verdict が含まれます — モデルの確率にかかわらず、昼光下では見えません
• OVATIONモデルは約5分ごとに更新され、約30～60分先まで予報します

---

noaa_spaceweather_get_solar_wind _ツール

• window_hours（1–168、デフォルトは3）は、約1分間隔で直近約24時間分を含むフィードを切り出します。resolution は系列の詳細度を設定します。reduced（デフォルト）は各系列を最大200レコードに制限し、各バケットの最高速度と最も南向きのBzを保持します。full はすべてのレコードを返します（24時間で系列ごとに約1,400件）。summary は系列を空にし、すべての見出しフィールドを返します（約2 KB）
• 古い順に、プラズマ（速度、密度、温度）と磁場（Bx/By/Bz/Bt GSM）の系列を返します。各レコードには観測衛星の名前が含まれます。また、すべての解像度で、ウィンドウ全体から算出した見出しフィールドbzStatus、bzMinInWindow、speedMaxInWindow、densityMaxInWindow、btMaxInWindow、bzSouthMinutesInWindowも返します
• latestFeedPlasmaTime／latestFeedMagTime／feedStalenessHoursにより、ウィンドウが空の場合とフィードが古い場合を区別できます

---

noaa_spaceweather_get_solar_activity _ツール

• flare_hours（1–168、デフォルトは24）は、フィードのローリング7日間から返すフレアイベントの発生時刻の範囲を設定します。include_regions（デフォルトはtrue）は、応答サイズを調整するために領域ごとの詳細を切り替えます
• 発生、ピーク、減衰のクラス、ピークフラックス、およびそれが示すNOAAのRレベル（0–5）を含む個別のフレアイベントを返します（フレア進行中は減衰がnull、SWPCがピークを記録していない場合はピークフィールドがnullになります）。また、フレアクラス（flareClassFull）付きのGOES X線フラックス、観測時刻付きの日次F10.7 cm電波フラックス、3日間のC/M/Xフレアおよびプロトンイベントの確率（cClassProbability、mClassProbability、xClassProbability、protonEventProbability。非推奨の*1Day名もstructuredContent内ではこれらの値を保持します）、および≥10 MeVのプロトンフラックスから求めたSレベルを返します
• include_regionsを指定すると、各活動領域の日斑面積、観測日にSWPCがその領域に帰属させたC/M/Xフレア件数、および翌日のフレア確率を返します

---

noaa_spaceweather_get_alerts _ツール

• active_only（デフォルトはtrue）を指定すると、有効な警報・注意報・アラートのみを保持し、取り消し済みまたは置き換えられたプロダクト、サマリー、および有効期間が終了したプロダクトを除外します。max_age_hours（1–720、デフォルトは48）は候補の遡及期間を設定します。active_onlyでは、有効期間の終了時刻がまだ先のプロダクトはこの範囲を超えていても残ります。それ以外の場合は、単純な経過時間の上限として適用されます
• 各レコードには、プロダクトの種類、NOAAのスケールとレベル（0は「スケールの記載なし」を意味し、深刻度がゼロという意味ではありません）、通し番号、解析済みの有効期間、cancelled、およびメッセージ全文が含まれます。active_onlyでは、応答に除外件数も理由別に含まれるため、結果が空の場合、「静穏」なのか「すべてがフィルタリングされた」のかを判断できます

---

機能

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

SWPC 固有の機能：

• SWPC のすべてのフィードは公開されており、キーは不要です。API キーは必要ありません。
• 単一の SpaceWeatherService が、すべての NOAA SWPC フィード（JSON プロダクトとプレーンテキストの予報解説の両方）を、1 つの fetchWithTimeout と withRetry の経路で処理します。これにより、どちらの経路でも上流の障害を同じ方法で分類します。また、すべての再試行処理は 45 秒の予算内で実行されるため、上流が応答しなくても、60 秒のクライアントタイムアウトより前に分類済みのエラーを返します。
• 多様なフィード形式を正規化します：複数の宇宙機の記録が混在する形式（太陽風）、キー付きオブジェクト（嵐のスケール）、座標の組（OVATION）、セクション区切りのテキスト（予報解説）。
• NOAA スケールを解釈します：生の Kp 6 →「G2 中程度の嵐 — 地磁気緯度約 55°までオーロラが見られる可能性があります」
• 応答ごとにフィードの鮮度を表示します：太陽風は約 1 分ごと、オーロラは約 5 分ごとに更新され、Kp は 3 時間間隔です。

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

• すべての応答に観測時刻を含め、エージェントがデータの鮮度を判断できるようにします。
• 生の値に加えて、平易な要約と判定を提供します。エージェントは指数を再解釈せずに表示したり、推論に利用したりできます。
• 太陽風の出力では Bz 成分を主要なフィールドとして提示します（南向きの Bz は嵐の主な要因です）。
• 回復のヒントを、再試行が有効かどうかに応じて分けた、型付きのエラー仕様を提供します。一時的なフィード障害は feed_unavailable →「30～60 秒後に再試行」となります。SWPC が提供しなくなったフィード経路は feed_moved →「再試行しても解決しません」となり、初回の試行で通知されます。

---

はじめに

公開ホストインスタンス

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

Claude Code の場合：

claude mcp add --transport http noaa-spaceweather-mcp-server https://noaa-spaceweather.caseyjhand.com/mcp

Cline の場合（cline_mcp_settings.json）：

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

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "noaa-spaceweather-mcp-server": {
      "url": "https://noaa-spaceweather.caseyjhand.com/mcp"
    }
  }
}

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

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加します。

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

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

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

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

{
  "mcpServers": {
    "noaa-spaceweather": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/noaa-spaceweather-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 キーは不要です。SWPC のすべてのフィードは公開されています。

インストール

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

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

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

cd noaa-spaceweather-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env if needed — all defaults work out of the box

---

設定

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_HOST	HTTP サーバーのホスト名。	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	エンドポイントのパス。	/mcp
MCP_SESSION_MODE	HTTP セッションモード。このプロジェクトでは明示的に stateless を使用します。auto は stateful に解決されます。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）。	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗した各ツール呼び出しの引数と結果をログに記録します。キー名で機密情報をマスキングし、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）でサイズを制限します。自由形式の値に含まれるシークレットはマスキングされません。	false
STORAGE_PROVIDER_TYPE	ストレージバックエンド。	in-memory
OTEL_ENABLED	OpenTelemetry 計測を有効にします。	false

ドメイン固有の API キーは必要ありません。省略可能な上書き設定の全一覧は .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 noaa-spaceweather-mcp-server .
docker run --rm -p 3010:3010 noaa-spaceweather-mcp-server

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

---

プロジェクト構成

パス	用途
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、サービスを初期化します。
src/services/space-weather/	SpaceWeatherService。NOAA SWPC のすべてのフィードを取得し、正規化します。
src/mcp-server/tools/definitions/	ツール定義（*.tool.ts）。ツールごとに 1 ファイルです。
tests/	src/ に対応する単体テストと統合テストです。
docs/	設計ドキュメントとディレクトリツリーです。

---

開発ガイド

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

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

---

コントリビューション

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

bun run devcheck
bun run test

---

ライセンス

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