ionis-mcp

A Model Context Protocol (MCP) server for HF radio propagation analytics, built on the IONIS dataset collection — 175M+ aggregated signatures derived from 14 billion WSPR, RBN, Contest, DXpedition, and PSK Reporter observations spanning 2005-2026.

Overview

IONIS (Ionospheric Neural Inference System) is an open-source machine learning system for predicting HF (shortwave) radio propagation. The datasets — curated from the world's largest amateur radio telemetry networks — are distributed as SQLite files on SourceForge.

ionis-mcp bridges those datasets to AI assistants via the Model Context Protocol. Install the package, download data, and Claude (Desktop or Code) can answer propagation questions using 11 specialized tools — no SQL required.

Example 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?"

Datasets

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.

Quick Start

# 1. Install
pip install ionis-mcp

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

# 3. Configure Claude (see below) and restart — tools appear automatically

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

Configure Your MCP Client

ionis-mcp works with any MCP-compatible client. Add the server config and restart — 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": "ionis-mcp"
    }
  }
}

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "ionis": {
      "command": "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": "ionis-mcp"
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "ionis": {
      "command": "ionis-mcp"
    }
  }
}

VS Code / GitHub Copilot

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

{
  "servers": {
    "ionis": {
      "command": "ionis-mcp"
    }
  }
}

Gemini CLI

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

{
  "mcpServers": {
    "ionis": {
      "command": "ionis-mcp"
    }
  }
}

Tools

Tool	Purpose
list_datasets	Show available datasets with row counts and file sizes
query_signatures	Flexible signature lookup — filter by source, band, grid, hour, month
band_openings	Hour-by-hour propagation profile for a path on a specific band
path_analysis	Complete path analysis across all bands, hours, months, and sources
solar_correlation	SFI effect on propagation — grouped by solar flux bracket
grid_info	Maidenhead grid decode with solar elevation computation
compare_sources	Cross-dataset comparison (WSPR vs RBN vs Contest vs PSKR)
dark_hour_analysis	Classify paths by solar geometry — both-day, cross-terminator, both-dark
solar_history	Historical solar indices for any date range
band_summary	Band overview — hour distribution, top grid pairs, distance range
current_conditions	Live propagation forecast — SFI, Kp, solar wind, band outlook, POTA/SOTA tips
get_version_info	Service version + upstream dataset version (fleet identity attestation)

Data Directory Layout

~/.ionis-mcp/data/                  (or $IONIS_DATA_DIR)
├── propagation/
│   ├── wspr-signatures/wspr_signatures_v2.sqlite      (8.4 GB, 93.6M rows)
│   ├── rbn-signatures/rbn_signatures.sqlite            (5.6 GB, 67.3M rows)
│   ├── contest-signatures/contest_signatures.sqlite    (424 MB, 5.7M rows)
│   ├── dxpedition-signatures/dxpedition_signatures.sqlite (22 MB, 260K rows)
│   └── pskr-signatures/pskr_signatures.sqlite          (606 MB, 8.4M rows)
├── solar/
│   ├── solar-indices/solar_indices.sqlite               (7.7 MB, 76.7K rows)
│   └── dscovr/dscovr_l1.sqlite                         (2.9 MB, 23K rows)
└── tools/
    ├── grid-lookup/grid_lookup.sqlite                   (1.1 MB, 31.7K rows)
    └── balloon-callsigns/balloon_callsigns_v2.sqlite    (116 KB, 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.

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 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

Testing with MCP Inspector

ionis-mcp --transport streamable-http --port 8000
# Open http://localhost:8000/mcp in browser

Related Projects

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

License

GPL-3.0-or-later

Citation

If you use the IONIS 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/