cyanheads/noaa-spaceweather-mcp-server

imageVersion imageLicense imageDocker imageMCP SDK imagenpm imageTypeScript imageBun

imageInstall in Claude Desktop imageInstall in Cursor imageInstall in VS Code

imageFramework

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

Overview

Space weather from NOAA's Space Weather Prediction Center: geomagnetic storms, Kp index, aurora forecasts, solar wind, solar activity, and active alerts. Check current conditions, see whether the aurora is visible where you are, or pull solar wind time series.

Tools

Capability reference

noaa_spaceweather_get_conditions tool

• include_discussion (bool, default false) is the only input; one call composes the noaa-scales.json and noaa-planetary-k-index.json feeds, plus the discussion.txt product when the discussion is requested
• Returns current Kp with its G-scale equivalent and aurora-latitude guidance, today's observed R/S/G levels, yesterday (the previous UTC day's assessed levels, null when the feed carries none), and SWPC's 3-day forecast starting today — forecast R and S carry probabilities rather than levels, and a null level means none was forecast, not level 0
• With include_discussion, the forecaster-written Forecast Discussion split into its topic sections (Solar Activity, Energetic Particle, Solar Wind, Geospace), each with its 24-hour summary and 3-day forecast text

noaa_spaceweather_get_kp_index tool

• window_days (1–7, default 1) bounds the observed series, and observedCount reports how many readings matched; the forecast is always SWPC's full 3-day series of forward-looking estimated/predicted rows
• Each record carries Kp, its G level and label, and aurora-latitude guidance. G levels follow SWPC's minus-third band floors — G1 starts at Kp 4.67 (5−), and only Kp 9 is G5

noaa_spaceweather_get_aurora_forecast tool

• latitude/longitude (WGS84) are optional but required together — one alone fails invalid_coordinates. Without them the call returns global metadata only: grid point count, global peak probability, and peak region
• With coordinates, localLookup carries the nearest 1°-grid probability, the geomagnetic latitude, the minimum Kp and G level needed there, the sun's elevation and darkness state (day, civil_twilight, nautical_twilight, dark) at the forecast time, the strongest reading within 1000 km poleward (horizonMaxPercent, horizonMaxLatitude, horizonDistanceKm), and a go/no-go verdict — not visible in daylight, whatever the model probability
• The OVATION model updates every ~5 minutes and forecasts ~30–90 minutes ahead (the solar wind's travel time from L1 to Earth)

noaa_spaceweather_get_solar_wind tool

• window_hours (1–168, default 3) slices a feed that carries roughly the last 24 hours at ~1-minute cadence. resolution sets series detail: reduced (default) caps each series at 200 records, keeping each bucket's fastest speed and most southward Bz; full returns every record (~1,400 per series over 24 hours); summary returns empty series and every headline field, about 2 KB
• Returns oldest-first plasma (speed, density, temperature) and magnetic-field (Bx/By/Bz/Bt GSM) series, each record naming its spacecraft, plus headline fields computed over the full window at every resolution: bzStatus, bzMinInWindow, speedMaxInWindow, densityMaxInWindow, btMaxInWindow, and bzSouthMinutesInWindow
• latestFeedPlasmaTime/latestFeedMagTime/feedStalenessHours distinguish an empty window from a stale feed

noaa_spaceweather_get_solar_activity tool

• flare_hours (1–168, default 24) bounds the flare events returned by onset over the feed's rolling 7 days; include_regions (default true) toggles per-region detail to control response size
• Returns discrete flare events with onset, peak, and decay classes, peak flux, and the NOAA R level (0–5) it implies (decay is null while a flare is in progress; peak fields are null when SWPC recorded no peak); GOES X-ray flux with its flare class (flareClassFull); the daily F10.7 cm radio flux with its observation time; 3-day C/M/X flare and proton-event probabilities (cClassProbability, mClassProbability, xClassProbability, protonEventProbability — the deprecated *1Day names still carry them in structuredContent); and the S level from ≥10 MeV proton flux
• With include_regions, each active region's sunspot area, the C/M/X flare counts SWPC attributed to it on its observation day, and its next-day flare probabilities

noaa_spaceweather_get_alerts tool

• active_only (default true) keeps in-force Warnings/Watches/Alerts, dropping cancelled and superseded products, Summaries, and products whose validity has ended. max_age_hours (1–720, default 48) bounds how far back candidates reach — under active_only a product whose validity end is still ahead survives it; otherwise it is a literal age cutoff
• Each record carries product type, NOAA scale and level (0 means "no scale stated," not zero severity), serial number, parsed validity window, cancelled, and full message text. Under active_only the response also counts what it excluded, by reason, so an empty result reads as "quiet" or "everything was filtered"

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

SWPC-specific:

• All SWPC feeds are public and keyless — no API keys required
• Single SpaceWeatherService wraps every NOAA SWPC feed — the JSON products and the plain-text forecast discussion — behind one fetchWithTimeout + withRetry funnel, so both paths classify an upstream failure the same way — and every retry ladder runs inside one 45-second budget, so a hung upstream still returns the classified error before a 60-second client timeout
• Heterogeneous feed normalization: interleaved multi-spacecraft records (solar wind), keyed objects (storm scales), coordinate triples (OVATION), section-delimited text (forecast discussion)
• 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, split on whether retrying can help: a transient feed failure is feed_unavailable → "Retry in 30–60 s"; a feed path SWPC no longer serves is feed_moved → "Retrying will not help", raised on the first attempt

Getting started

Connect to the hosted instance, no install:

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

Or run it locally:

claude mcp add noaa-spaceweather-mcp-server -- npx -y @cyanheads/noaa-spaceweather-mcp-server

For other clients, add this to the MCP config file:

{
  "mcpServers": {
    "noaa-spaceweather-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/noaa-spaceweather-mcp-server"]
    }
  }
}

No API key is needed — every SWPC feed is public. For Docker or a source build, see Running the server.

Configuration

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

Running the server

Local development

Requires Bun v1.4.0 or higher (or Node.js v24+).

• Clone and install:

  git clone https://github.com/cyanheads/noaa-spaceweather-mcp-server.git
  cd noaa-spaceweather-mcp-server && bun install
  cp .env.example .env   # all defaults work out of the box
  

• 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 run --rm -p 3010:3010 ghcr.io/cyanheads/noaa-spaceweather-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/noaa-spaceweather-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/noaa-spaceweather-mcp-server:latest"]. To build locally, docker build -t noaa-spaceweather-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

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 are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.