Metadata-Version: 2.4
Name: spaceweather-mcp
Version: 0.1.0
Summary: Space-weather and geomagnetic conditions (NOAA SWPC planetary Kp, solar wind, storm scales, alerts, 27-day outlook) as a Model Context Protocol server.
Project-URL: Homepage, https://github.com/hoon1983/spaceweather-mcp
Project-URL: Repository, https://github.com/hoon1983/spaceweather-mcp
Project-URL: Issues, https://github.com/hoon1983/spaceweather-mcp/issues
Author: matt
License: MIT
License-File: LICENSE
Keywords: aurora,geomagnetic,heliophysics,kp-index,mcp,model-context-protocol,noaa,solar-wind,space-weather,swpc
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: fastmcp>=3.0
Requires-Dist: httpx[http2]>=0.27
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# spaceweather-mcp

<!-- mcp-name: io.github.hoon1983/spaceweather-mcp -->

A Model Context Protocol server for **space weather and geomagnetic conditions** — solar flares, the solar wind, geomagnetic storms (Kp/Dst), radiation storms, sunspot regions, aurora forecasts, and a catalogued event history — so an AI agent can answer "what's the sun/space weather doing right now, and will I see aurora?" from authoritative data.

Sibling to [seismic-mcp](https://github.com/hoon1983/seismic-mcp): that one reconciles earthquakes across agencies; this one reports solar/geomagnetic conditions. They install side by side.

## Status

**15 tools across 4 data sources — all live and verified.** Everything is U.S./NASA public domain except the Kyoto Dst index, which is non-commercial and clearly labeled (and kept segregated from the public-domain feeds).

## Tools

**NOAA SWPC** (public domain)
| Tool | Returns |
| --- | --- |
| `get_conditions_now` | One-call snapshot: Kp, Bz/Bt, wind speed/density, G/S/R, storm flag, summary |
| `get_kp_index` | Observed planetary Kp series (~1 week) |
| `get_kp_forecast` | NOAA 3-day Kp forecast |
| `get_solar_wind` | L1 magnetic field + plasma (`window`: `1-day`/`7-day`) |
| `get_alerts` | Recent SWPC alerts/watches/warnings |
| `get_noaa_scales` | G/S/R scales for today + 3 days |
| `get_27day_outlook` | Daily F10.7 flux, Ap, largest Kp for 27 days |
| `get_solar_flares` | Recent GOES X-ray flares (C/M/X class events) |
| `get_radiation_storm` | Current proton flux + NOAA S-scale (radiation storm) |
| `get_solar_regions` | Today's sunspot regions + C/M/X flare probabilities |
| `get_aurora_forecast` | OVATION aurora probability (pass lat/lon for a local %) |

**NASA DONKI** (public domain) — `get_space_weather_events` (CME / GST / FLR / SEP / IPS / HSS event catalog)

**USGS Geomagnetism** (public domain) — `list_observatories`, `get_observatory` (magnetometer X/Y/Z/F)

**Kyoto WDC** (non-commercial) — `get_dst` (hourly disturbance storm-time index)

## Run

```bash
uv run spaceweather-mcp        # stdio MCP server
uv run pytest                  # tests
```

Add to `claude_desktop_config.json` (after publishing to PyPI):

```json
{ "mcpServers": { "spaceweather": { "command": "uvx", "args": ["spaceweather-mcp"] } } }
```

## Data sources, attribution & licensing

- **NOAA SWPC** (`services.swpc.noaa.gov`) — U.S. public domain. Credit NOAA SWPC.
- **NASA DONKI** via CCMC (`kauai.ccmc.gsfc.nasa.gov/DONKI`) — U.S. public domain (no API key needed). Credit NASA/CCMC DONKI.
- **USGS Geomagnetism** (`geomag.usgs.gov`) — U.S. public domain. Credit the U.S. Geological Survey. (Sourced directly from USGS, not via INTERMAGNET, to keep public-domain status.)
- **Kyoto WDC for Geomagnetism** — Dst index, **non-commercial use only**: acknowledge "WDC for Geomagnetism, Kyoto", cite the Dst DOI; real-time values are provisional. The non-commercial restriction is documented in the `get_dst` tool description and the `DstReading` schema (both surfaced to MCP clients), and this feed is kept separate from the public-domain ones.

> ⚠️ Only the Kyoto Dst feed is non-commercial. It is segregated, and its non-commercial terms are stated in the tool/schema docs the client sees, so a downstream commercial user is not silently bound by those terms.

**Deliberately not included:** INTERMAGNET and SILSO sunspot number (both CC BY-**NC** — would taint the otherwise commercially-usable server); JPL Horizons ephemeris (different domain). F10.7 is available via `get_27day_outlook`; GFZ Hp30/Hp60 high-cadence indices (CC BY 4.0) are a possible future add.

## Safety

Informational only. **Not** for operational decisions affecting power grids, aviation, satellites, or human safety — consult official NOAA SWPC products for those. Real-time values are preliminary and routinely revised.
