ionis-mcp

MCP server for HF radio propagation analytics on the IONIS-AI datasets — 175M+ aggregated signatures derived from 14 billion WSPR, RBN, contest, DXpedition and PSK Reporter observations, 2005–2026 — through any MCP-compatible AI assistant.

Part of the qso-graph project. No authentication required. The datasets are downloaded once (see Datasets).

Install

uv tool install ionis-mcp         # puts ionis-mcp and ionis-download on your PATH
ionis-download --bundle minimal   # 454 MB; see Datasets for the other bundles

Or with pip: pip install ionis-mcp.

Tools

What is IONIS-AI?

IONIS-AI is an open-source machine learning system for predicting HF (shortwave) radio propagation. Its datasets are curated from the world's largest amateur radio telemetry networks and distributed as SQLite files on SourceForge. ionis-mcp lets an assistant answer propagation questions from them, no SQL required.

All signature tables share an identical 13-column schema (tx_grid, rx_grid, band, hour, month, median_snr, spot_count, snr_std, reliability, avg_sfi, avg_kp, avg_distance, avg_azimuth) — ready for cross-source analysis.

Datasets

# 1. Install
uv tool install ionis-mcp

# 2. Download datasets (to default location: ~/.ionis-mcp/data/)
ionis-download --bundle minimal          # 454 MB  — contest + solar + grids
ionis-download --bundle recommended      # 1.1 GB  — adds PSKR + DSCOVR
ionis-download --bundle full             # 16.2 GB — all 9 datasets

# 3. Configure your MCP client (see Quick Start) and restart

That's it. Both ionis-download and ionis-mcp use the same default data directory. No environment variables needed.

Default data directory

Override with a custom path:

# Download to custom location
ionis-download --bundle minimal /path/to/my/data

# Tell the server where to find it
ionis-mcp --data-dir /path/to/my/data
# or
export IONIS_DATA_DIR=/path/to/my/data

Download individual datasets

# Pick specific datasets
ionis-download --datasets wspr,rbn,grids,solar

# See all available datasets and bundles
ionis-download --list

# Re-download (overwrite existing)
ionis-download --bundle minimal --force

If a download is interrupted (a dropped connection, Ctrl-C), run the same command again: it picks up where it stopped. Brief network errors are retried on their own. Sizes are in MB and GB (1 MB = 1,000,000 bytes).

Data directory layout

~/.ionis-mcp/data/                  (or $IONIS_DATA_DIR)
├── propagation/
│   ├── wspr-signatures/wspr_signatures_v2.sqlite      (9.1 GB, 93.6M rows)
│   ├── rbn-signatures/rbn_signatures.sqlite            (6.0 GB, 67.3M rows)
│   ├── contest-signatures/contest_signatures.sqlite    (445 MB, 5.7M rows)
│   ├── dxpedition-signatures/dxpedition_signatures.sqlite (22 MB, 260K rows)
│   └── pskr-signatures/pskr_signatures.sqlite          (635 MB, 8.4M rows)
├── solar/
│   ├── solar-indices/solar_indices.sqlite               (8.0 MB, 76.7K rows)
│   └── dscovr/dscovr_l1.sqlite                         (3.0 MB, 23K rows)
└── tools/
    ├── grid-lookup/grid_lookup.sqlite                   (1.1 MB, 31.7K rows)
    └── balloon-callsigns/balloon_callsigns_v2.sqlite    (0.1 MB, 1.5K rows)

The server works with whatever datasets are present. Missing datasets degrade gracefully — tools that need unavailable data return clear messages instead of errors.

Quick Start

Configure your MCP client

ionis-mcp works with any MCP-compatible client. Add the server config and restart. The tools appear automatically.

If you downloaded data to a custom location, add "env": { "IONIS_DATA_DIR": "/path/to/data" } to any config below.

Claude Desktop

Add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "ionis": {
      "command": "uvx",
      "args": ["ionis-mcp"]
    }
  }
}

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "ionis": {
      "command": "uvx",
      "args": ["ionis-mcp"]
    }
  }
}

ChatGPT Desktop

ChatGPT supports MCP via the OpenAI Agents SDK. Add under Settings > Apps & Connectors, or configure in your agent definition:

{
  "mcpServers": {
    "ionis": {
      "command": "uvx",
      "args": ["ionis-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "ionis": {
      "command": "uvx",
      "args": ["ionis-mcp"]
    }
  }
}

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "ionis": {
      "command": "uvx",
      "args": ["ionis-mcp"]
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json (global) or .gemini/settings.json (project):

{
  "mcpServers": {
    "ionis": {
      "command": "uvx",
      "args": ["ionis-mcp"]
    }
  }
}

Installed with pip instead? Use "command": "ionis-mcp" in any config above.

Ask questions

"When is 20m open from Idaho to Europe?"

"How does solar flux affect 15m propagation?"

"Show me 10m paths at 03z where both stations are in the dark"

"Compare WSPR and RBN observations on 20m FN31 to JO51"

"What are the current band conditions? I'm heading out for POTA."

"What were the solar conditions during the February 2026 geomagnetic storm?"

Architecture

• Transport: stdio (Claude Desktop / Claude Code) or streamable-http (MCP Inspector)
• Database: Read-only sqlite3 connections (?mode=ro) — no writes, ever
• Query safety: All queries use parameterized SQL (? placeholders), result limits enforced server-side (max 1000 rows)
• Grid lookup: 31.7K Maidenhead grids loaded into memory at startup (~2 MB) for instant lat/lon resolution
• Solar geometry: Pure Python solar elevation computation (same algorithm as the IONIS-AI training pipeline) — classifies endpoints as day/twilight/night for propagation context
• Cross-source queries: Each SQLite database opened separately, results merged in Python with source labels

MCP Inspector

ionis-mcp --transport streamable-http --port 8000

Then open the MCP Inspector at http://localhost:8000/mcp.

Development

git clone https://github.com/qso-graph/ionis-mcp.git
cd ionis-mcp
uv sync --group dev
uv run pytest

Related Projects

License

GPL-3.0-or-later

Citation

If you use the IONIS-AI datasets in research, please cite:

Beam, G. (KI7MT). IONIS: Ionospheric Neural Inference System — HF Propagation Prediction Datasets. SourceForge, 2026. https://sourceforge.net/projects/ionis-ai/