# Space Weather Data MCP Server

An MCP (Model Context Protocol) server that gives AI assistants access to real-time space weather data and forecasts from NOAA's Space Weather Prediction Center (SWPC).

## What It Does

This server exposes NOAA's SWPC data services to any MCP-compatible AI client. The assistant can browse the data directory, fetch live observations and forecasts, look up product definitions, and interpret values using built-in space weather knowledge — all without leaving the conversation.

**Tools** (callable by the AI on demand):

| Tool | Description |
|---|---|
| `list_known_paths` | Curated map of the SWPC data server layout and notable files |
| `list_directory` | Browse any directory on the SWPC data server |
| `fetch_file` | Fetch a JSON or text data file and return its contents |
| `get_space_weather_scales` | NOAA G/S/R storm scales and solar flare A–X classification |
| `list_products` | Catalog of all SWPC products with descriptions and data file paths |
| `describe_product` | Fetch the full description of any SWPC product from the NOAA website |
| `get_data_file_info` | Field definitions and interpretation guide for key JSON data files |

**Prompts** (pre-built context bundles):

| Prompt | Description |
|---|---|
| `get_forecast` | Fetches the 3-day forecast, geomagnetic forecast, forecast discussion, SGARF, and advisory outlook — combined into one block |
| `get_kp_index` | Fetches the NOAA Planetary K-index (3-hour) and daily geomagnetic indices |
| `get_dst_index` | Fetches the Kyoto Dst index (hourly) with an interpretation guide prepended |

## Data Source

All data comes from NOAA SWPC's public data server:

- **Data**: `https://services.swpc.noaa.gov` (JSON + text files, no API key required)
- **Product info**: `https://www.swpc.noaa.gov/products-and-data`

No authentication is required. Data is provided by NOAA as a public service.

## Requirements

- Python 3.14+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

## Installation

```bash
git clone https://github.com/JimFlannery/space-weather-data-mcp.git
cd space-weather-data-mcp
uv sync
```

## Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "spaceweather": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/space-weather-data-mcp",
        "main.py"
      ]
    }
  }
}
```

**Config file locations:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

### VS Code (Copilot / MCP extension)

Add to your VS Code `settings.json`:

```json
{
  "mcp.servers": {
    "spaceweather": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/space-weather-data-mcp",
        "main.py"
      ]
    }
  }
}
```

### Development / Testing

Run the MCP Inspector to test tools and prompts interactively:

```bash
uv run mcp dev main.py
```

## Example Queries

Once connected to an MCP client, you can ask things like:

- *"What is the current space weather forecast?"*
- *"Is there a geomagnetic storm in progress? Check the Kp index."*
- *"What are today's active solar regions and their flare probabilities?"*
- *"Fetch the latest GOES X-ray flux and classify any solar flares."*
- *"What does a Kp of 7 mean for power grids?"*
- *"Show me the Dst index and explain whether we're in a storm's main phase or recovery phase."*

## Space Weather Scales Quick Reference

| Scale | Measures | Range | Storm starts at |
|---|---|---|---|
| **G** (Geomagnetic) | Kp index | G1–G5 | G1 (Kp = 5) |
| **S** (Solar Radiation) | ≥10 MeV proton flux | S1–S5 | S1 (10 pfu) |
| **R** (Radio Blackout) | X-ray flux (0.1–0.8 nm) | R1–R5 | R1 (M1 flare) |

Solar flares: **A → B → C → M → X** (each class is 10× stronger; X-class is open-ended).

Use the `get_space_weather_scales` tool for the full threshold and effects table.

## License

MIT — see [LICENSE](LICENSE).