io.github.IONIS-AI/ionis-mcp
HF propagation analytics. 175M WSPR/RBN signatures, band openings, solar correlation.
Ask AI about io.github.IONIS-AI/ionis-mcp
Powered by Claude Β· Grounded in docs
I know everything about io.github.IONIS-AI/ionis-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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_conditions | 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 |
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
sqlite3connections (?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/
