io.github.cyanheads/noaa-spaceweather-mcp-server

Official6 tools

by cyanheads · TypeScript

NOAA SWPC space weather: storm scales, Kp index, aurora forecasts, solar wind, activity, alerts.

Provides NOAA space weather data including storm scales, aurora forecasts, and solar activity alerts.

Topics

ai-agentsai-toolsauroracyanheadsgeomagneticmcpmcp-servermodel-context-protocolnoaaspace-weatherswpctypescript

Captured live from the server via tools/list.

noaa_spaceweather_get_conditions

Current space-weather snapshot: NOAA R/S/G storm scales (today + 3-day forecast), latest Kp index with its G-scale equivalent and aurora-visibility latitude, and a plain-language status summary. The quickest way to answer "is anything happening right now?" — use before deciding whether to drill into solar wind (noaa_spaceweather_get_solar_wind), aurora (noaa_spaceweather_get_aurora_forecast), or alert details (noaa_spaceweather_get_alerts).

No parameters.

noaa_spaceweather_get_alerts

Active SWPC alerts, watches, and warnings — parsed into structured records with product type, severity level, issue time, validity window, and plain text. Covers geomagnetic storms, radio blackouts, radiation storms, and aurora bulletins. With active_only=false, also returns informational summaries and expired notices. max_age_hours controls how far back to look (default 48 h); the SWPC feed keeps all historical records and has no built-in expiry.

Parameters (2)

active_onlyboolean
When true (default), return only Warnings, Watches, and Alerts; exclude Summaries and Other. Set false to return all products.
max_age_hoursnumber
Maximum age of alerts to return, in hours (default 48). The SWPC feed retains all historical records — this window prevents returning weeks of historical notices as "active."

noaa_spaceweather_get_kp_index

Planetary K-index (0–9 geomagnetic activity scale) — recent observed 3-hour values with their NOAA G-scale equivalents and aurora-latitude guidance, plus the 3-day Kp forecast series. Kp is the primary driver of aurora visibility and geomagnetic storm severity: Kp≥5 is G1, Kp≥7 is G3 (aurora to ~50°), Kp≥9 is G5 extreme. Use noaa_spaceweather_get_conditions for a combined snapshot including storm scales; use this tool when you need the Kp time series or forecast detail.

Parameters (1)

window_daysinteger
Number of past days of observed Kp to return (1–7, default 1). Larger windows show trend context.

noaa_spaceweather_get_solar_wind

Real-time solar wind data from DSCOVR at L1: proton speed (km/s), density (n/cm³), temperature (K), and the critical Bz component (southward Bz = negative = storm driver). Returns the recent plasma and magnetic field time series within the requested window. Bz < −10 nT for sustained periods is a primary geomagnetic storm trigger — use alongside noaa_spaceweather_get_kp_index to see whether elevated solar wind has translated into a geomagnetic storm.

Parameters (1)

window_hoursinteger
Hours of recent solar wind history to return (1–168, default 3). Feeds update ~every 1 min.

noaa_spaceweather_get_solar_activity

Solar flare and radiation storm picture: recent GOES X-ray flux with flare-class labels (A/B/C/M/X), 3-day flare-class probabilities (C/M/X), active solar regions with per-region flare probabilities, and GOES integral proton flux at ≥10 MeV with NOAA S-scale. For operators tracking HF radio blackout (R-scale, driven by X-ray) and radiation storm risk (S-scale, driven by protons). Active region data helps identify which region is driving current activity.

Parameters (1)

include_regionsboolean
Include active solar region details (default true). Set false to skip region data and reduce response size.

noaa_spaceweather_get_aurora_forecast

OVATION model aurora forecast for the next ~30–60 min: global grid of aurora probability percentages by latitude/longitude (1° resolution). With optional coordinates, returns the local aurora probability at the nearest grid point, the minimum Kp needed for aurora at that latitude, and a plain-language go/no-go verdict. Without coordinates, returns only global metadata. Data updates every ~5 minutes. Coordinates are geographic (WGS84), not geomagnetic.

Parameters (2)

latitudenumber
Geographic latitude in degrees (−90 to 90). Provide with longitude for a local aurora probability lookup.
longitudenumber
Geographic longitude in degrees (−180 to 180). Provide with latitude for a local aurora probability lookup.

README.md12 KBView on GitHub

<div align="center"> <h1>@cyanheads/noaa-spaceweather-mcp-server</h1> <p><b>Query NOAA SWPC space weather: geomagnetic storm scales, Kp index, aurora forecasts, solar wind, solar activity, and alerts via MCP. STDIO or Streamable HTTP.</b> <div>6 Tools</div> </p> </div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://noaa-spaceweather.caseyjhand.com/mcp

</div>

Tools

Six tools covering the full NOAA SWPC space weather surface — from a quick status heartbeat to deep solar and geomagnetic data:

Tool	Description
`noaa_spaceweather_get_conditions`	Current space-weather snapshot: NOAA R/S/G storm scales, latest Kp, and a plain-language status summary
`noaa_spaceweather_get_kp_index`	Planetary K-index (0–9) — recent observed 3-hour values with G-scale equivalents and aurora-latitude guidance, plus 3-day forecast
`noaa_spaceweather_get_aurora_forecast`	OVATION model aurora forecast: global probability grid, optional local lookup by coordinates with go/no-go verdict
`noaa_spaceweather_get_solar_wind`	Real-time solar wind from DSCOVR: speed, proton density, temperature, and the critical Bz component — explains why current geomagnetic conditions exist
`noaa_spaceweather_get_solar_activity`	Solar flare picture: GOES X-ray flux, 3-day flare-class probabilities, active solar regions with per-region probabilities, and solar radiation storm level
`noaa_spaceweather_get_alerts`	Active SWPC alerts, watches, and warnings — structured records with product type, severity, issue time, validity window, and full message text

`noaa_spaceweather_get_conditions`

The heartbeat tool. Use it first — it composes storm scales + current Kp into a single snapshot with a plain-language summary.

Returns today's R/S/G storm scales plus a 3-day forecast
Current Kp with G-scale equivalent and aurora-visibility latitude guidance
Plain-language summary: "Quiet conditions" vs. "G2 moderate geomagnetic storm in progress"
Data sourced from noaa-scales.json + noaa-planetary-k-index.json

`noaa_spaceweather_get_kp_index`

Planetary K-index time series for geomagnetic activity tracking.

window_days parameter (1–7, default 1) — recent 3-hour observed values
Each record includes Kp value, G-scale equivalent, aurora-latitude guidance, and observation time
Separate 3-day forecast series with predicted Kp and NOAA G-scale labels

`noaa_spaceweather_get_aurora_forecast`

OVATION model aurora probability at 1° resolution, updated every ~5 minutes.

Without coordinates: global metadata — grid point count, global peak probability, peak region
With coordinates (latitude, longitude): nearest-grid-point lookup, minimum Kp required at that latitude, and a plain-language verdict ("Good aurora chance (42%) — Kp≥6 needed at this latitude")
Covers both hemispheres; coordinates are geographic (WGS84)

`noaa_spaceweather_get_solar_wind`

DSCOVR satellite real-time solar wind plasma and magnetic field.

window_hours parameter (1–168, default 3) — time series sliced client-side from 7-day feed
Plasma: speed (km/s), proton density (n/cm³), temperature
Bz component (southward Bz = storm driver) surfaced prominently in output and format
Bt (total field magnitude) and GSM vector components

`noaa_spaceweather_get_solar_activity`

Solar flare and radiation storm picture from GOES and SWPC probabilities.

GOES primary X-ray flux in the 0.1–0.8 nm band (R-scale driver)
3-day C/M/X flare-class probabilities
Active solar regions with per-region flare and proton probabilities when include_regions: true (default)
Solar radiation storm (S-scale) level from ≥10 MeV integral proton flux

`noaa_spaceweather_get_alerts`

Active SWPC alerts, watches, and warnings from the products/alerts.json feed.

Structured product metadata: type (Watch/Warning/Alert/Summary), issue time, and ISO 8601 validity window parsed from the message body (Valid From/To, Now Valid Until, or Begin/End Time)
Parsed severity from product code (G/R/S-scale, K-index level)
Filtered to active-only by default (active_only: true); set false for recent history
Full raw message text preserved for downstream display

Features

Built on @cyanheads/mcp-ts-core:

Declarative tool definitions — single file per tool, framework handles registration and validation
Unified error handling — handlers throw, framework catches, classifies, and formats
Pluggable auth: none, jwt, oauth
Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
Structured logging with optional OpenTelemetry tracing
STDIO and Streamable HTTP transports

Space weather domain:

All SWPC feeds are public and keyless — no API keys required
Single SpaceWeatherService wraps all six NOAA SWPC JSON feeds with fetchWithTimeout + withRetry
Heterogeneous feed normalization: array-of-arrays (solar wind), keyed objects (storm scales), coordinate triples (OVATION)
NOAA scale interpretation: raw Kp 6 → "G2 moderate storm — aurora possible to ~55° geomagnetic latitude"
Feed freshness surfaced per-response: solar wind updates ~1 min, aurora ~5 min, Kp 3-hour intervals

Agent-friendly output:

Observed timestamps on every response so agents can reason about data freshness
Plain-language summaries and verdicts alongside raw values — agents can display or reason without re-interpreting indices
Bz component surfaced as a first-class field in solar wind output (southward Bz = primary storm driver)
Typed error contracts with recovery hints: feed_unavailable → "Retry in 30–60 s"

Getting started

Public Hosted Instance

A public instance is available at https://noaa-spaceweather.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

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

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

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

Or with npx (no Bun required):

json

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

Or with Docker:

json

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

For Streamable HTTP, set the transport and start the server:

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

Prerequisites

Bun v1.3.0 or higher (or Node.js v24+).
No API keys required — all SWPC feeds are public.

Installation

Clone the repository:

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

Navigate into the directory:

cd noaa-spaceweather-mcp-server

Install dependencies:

bun install

Configure environment:

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

Configuration

Variable	Description	Default
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for HTTP server.	`3010`
`MCP_HTTP_HOST`	Hostname for HTTP server.	`127.0.0.1`
`MCP_HTTP_ENDPOINT_PATH`	Endpoint path.	`/mcp`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend.	`in-memory`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation.	`false`

No domain-specific API keys are required. See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

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

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/noaa-spaceweather-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Path	Purpose
`src/index.ts`	`createApp()` entry point — registers tools and inits the service.
`src/services/space-weather/`	`SpaceWeatherService` — fetches and normalizes all NOAA SWPC feeds.
`src/mcp-server/tools/definitions/`	Tool definitions (`*.tool.ts`) — one file per tool.
`tests/`	Unit and integration tests mirroring `src/`.
`docs/`	Design doc and directory tree.

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
Register new tools via the barrel in src/mcp-server/tools/definitions/index.ts
Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

claude_desktop_config.json

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