io.github.IONIS-AI/ionis-mcp

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

Tool	Description	Key Parameters
list_datasets	Available datasets with row counts and file sizes	—
query_signatures	Signature lookup filtered by source, band, grid, hour, month	source, band, tx_grid, rx_grid, hour, month
band_openings	Hour-by-hour propagation profile for a path on one band	tx_grid, rx_grid, band
path_analysis	A path across all bands, hours, months and sources	tx_grid, rx_grid, source
solar_correlation	Solar flux effect on propagation, by SFI bracket	band, tx_grid, rx_grid
grid_info	Maidenhead grid decode with solar elevation	grid, hour, month
compare_sources	Cross-dataset comparison (WSPR vs RBN vs contest vs PSKR)	tx_grid, rx_grid, band
dark_hour_analysis	Paths by solar geometry: both-day, cross-terminator, both-dark	band, hour, month
solar_history	Historical solar indices for a date range	start_date, end_date, resolution
band_summary	Band overview: hour distribution, top grid pairs, distances	band, source
current_conditions	Live forecast: SFI, Kp, solar wind, band outlook, POTA/SOTA tips	qth_grid
get_version_info	Service version + upstream spec version (fleet identity attestation)	—

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.

Source	Signatures	Raw Observations	SNR Type	Years
WSPR	93.6M	10.9B beacon spots	Measured (-30 to +20 dB)	2008-2026
RBN	67.3M	2.3B CW/RTTY spots	Measured (8-29 dB)	2009-2026
CQ Contests	5.7M	234M SSB/RTTY QSOs	Anchored (+10/0 dB)	2005-2025
DXpeditions	260K	3.9M rare-grid paths	Measured	2009-2025
PSK Reporter	8.4M	514M+ FT8/WSPR spots	Measured (-34 to +38 dB)	Feb 2026+
Solar Indices	—	77K daily/3-hour records	SFI, SSN, Kp, Ap	2000-2026
DSCOVR L1	—	23K solar wind samples	Bz, speed, density	Feb 2026+

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

Platform	Location
Linux / macOS	~/.ionis-mcp/data/
Windows	%LOCALAPPDATA%\ionis-mcp\data\

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

Repository	Purpose
ionis-validate	IONIS-AI model validation suite (PyPI)
IONIS-AI datasets	Distributed dataset files (SourceForge)

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/