{
  "markdown": "<!-- mcp-name: io.github.qso-graph/ionis-mcp -->\n# ionis-mcp\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for HF radio propagation analytics, built on the [IONIS](https://ionis-ai.com/) dataset collection — 175M+ aggregated signatures derived from 14 billion WSPR, RBN, Contest, DXpedition, and PSK Reporter observations spanning 2005-2026.\n\n## Overview\n\nIONIS (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](https://sourceforge.net/projects/ionis-ai/).\n\n**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.\n\n**Example questions:**\n- \"When is 20m open from Idaho to Europe?\"\n- \"How does solar flux affect 15m propagation?\"\n- \"Show me 10m paths at 03z where both stations are in the dark\"\n- \"Compare WSPR and RBN observations on 20m FN31 to JO51\"\n- \"What are the current band conditions? I'm heading out for POTA.\"\n- \"What were the solar conditions during the February 2026 geomagnetic storm?\"\n\n## Datasets\n\n| Source | Signatures | Raw Observations | SNR Type | Years |\n|--------|-----------|-----------------|----------|-------|\n| [WSPR](https://www.wsprnet.org/) | 93.6M | 10.9B beacon spots | Measured (-30 to +20 dB) | 2008-2026 |\n| [RBN](https://reversebeacon.net/) | 67.3M | 2.3B CW/RTTY spots | Measured (8-29 dB) | 2009-2026 |\n| [CQ Contests](https://cqww.com/) | 5.7M | 234M SSB/RTTY QSOs | Anchored (+10/0 dB) | 2005-2025 |\n| [DXpeditions](https://www.ng3k.com/misc/adxo.html) | 260K | 3.9M rare-grid paths | Measured | 2009-2025 |\n| [PSK Reporter](https://pskreporter.info/) | 8.4M | 514M+ FT8/WSPR spots | Measured (-34 to +38 dB) | Feb 2026+ |\n| Solar Indices | — | 77K daily/3-hour records | SFI, SSN, Kp, Ap | 2000-2026 |\n| DSCOVR L1 | — | 23K solar wind samples | Bz, speed, density | Feb 2026+ |\n\nAll 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.\n\n## Quick Start\n\n```bash\n# 1. Install\npip install ionis-mcp\n\n# 2. Download datasets (to default location: ~/.ionis-mcp/data/)\nionis-download --bundle minimal          # ~430 MB — contest + solar + grids\nionis-download --bundle recommended      # ~1.1 GB — adds PSKR + DSCOVR\nionis-download --bundle full             # ~15 GB  — all 9 datasets\n\n# 3. Configure Claude (see below) and restart — tools appear automatically\n```\n\nThat's it. Both `ionis-download` and `ionis-mcp` use the same default data directory. No environment variables needed.\n\n### Default Data Directory\n\n| Platform | Location |\n|----------|----------|\n| Linux / macOS | `~/.ionis-mcp/data/` |\n| Windows | `%LOCALAPPDATA%\\ionis-mcp\\data\\` |\n\nOverride with a custom path:\n\n```bash\n# Download to custom location\nionis-download --bundle minimal /path/to/my/data\n\n# Tell the server where to find it\nionis-mcp --data-dir /path/to/my/data\n# or\nexport IONIS_DATA_DIR=/path/to/my/data\n```\n\n### Download Individual Datasets\n\n```bash\n# Pick specific datasets\nionis-download --datasets wspr,rbn,grids,solar\n\n# See all available datasets and bundles\nionis-download --list\n\n# Re-download (overwrite existing)\nionis-download --bundle minimal --force\n```\n\n## Configure Your MCP Client\n\nionis-mcp works with any MCP-compatible client. Add the server config and restart — tools appear automatically.\n\nIf you downloaded data to a custom location, add `\"env\": { \"IONIS_DATA_DIR\": \"/path/to/data\" }` to any config below.\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json` (`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\\Claude\\` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"ionis\": {\n      \"command\": \"ionis-mcp\"\n    }\n  }\n}\n```\n\n### Claude Code\n\nAdd to `.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"ionis\": {\n      \"command\": \"ionis-mcp\"\n    }\n  }\n}\n```\n\n### ChatGPT Desktop\n\nChatGPT supports MCP via the [OpenAI Agents SDK](https://developers.openai.com/api/docs/mcp/). Add under Settings > Apps & Connectors, or configure in your agent definition:\n\n```json\n{\n  \"mcpServers\": {\n    \"ionis\": {\n      \"command\": \"ionis-mcp\"\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):\n\n```json\n{\n  \"mcpServers\": {\n    \"ionis\": {\n      \"command\": \"ionis-mcp\"\n    }\n  }\n}\n```\n\n### VS Code / GitHub Copilot\n\nAdd to `.vscode/mcp.json` in your workspace:\n\n```json\n{\n  \"servers\": {\n    \"ionis\": {\n      \"command\": \"ionis-mcp\"\n    }\n  }\n}\n```\n\n### Gemini CLI\n\nAdd to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):\n\n```json\n{\n  \"mcpServers\": {\n    \"ionis\": {\n      \"command\": \"ionis-mcp\"\n    }\n  }\n}\n```\n\n## Tools\n\n| Tool | Purpose |\n|------|---------|\n| `list_datasets` | Show available datasets with row counts and file sizes |\n| `query_signatures` | Flexible signature lookup — filter by source, band, grid, hour, month |\n| `band_openings` | Hour-by-hour propagation profile for a path on a specific band |\n| `path_analysis` | Complete path analysis across all bands, hours, months, and sources |\n| `solar_correlation` | SFI effect on propagation — grouped by solar flux bracket |\n| `grid_info` | Maidenhead grid decode with solar elevation computation |\n| `compare_sources` | Cross-dataset comparison (WSPR vs RBN vs Contest vs PSKR) |\n| `dark_hour_analysis` | Classify paths by solar geometry — both-day, cross-terminator, both-dark |\n| `solar_history` | Historical solar indices for any date range |\n| `band_summary` | Band overview — hour distribution, top grid pairs, distance range |\n| `current_conditions` | Live propagation forecast — SFI, Kp, solar wind, band outlook, POTA/SOTA tips |\n| `get_version_info` | Service version + upstream dataset version (fleet identity attestation) |\n\n## Data Directory Layout\n\n```\n~/.ionis-mcp/data/                  (or $IONIS_DATA_DIR)\n├── propagation/\n│   ├── wspr-signatures/wspr_signatures_v2.sqlite      (8.4 GB, 93.6M rows)\n│   ├── rbn-signatures/rbn_signatures.sqlite            (5.6 GB, 67.3M rows)\n│   ├── contest-signatures/contest_signatures.sqlite    (424 MB, 5.7M rows)\n│   ├── dxpedition-signatures/dxpedition_signatures.sqlite (22 MB, 260K rows)\n│   └── pskr-signatures/pskr_signatures.sqlite          (606 MB, 8.4M rows)\n├── solar/\n│   ├── solar-indices/solar_indices.sqlite               (7.7 MB, 76.7K rows)\n│   └── dscovr/dscovr_l1.sqlite                         (2.9 MB, 23K rows)\n└── tools/\n    ├── grid-lookup/grid_lookup.sqlite                   (1.1 MB, 31.7K rows)\n    └── balloon-callsigns/balloon_callsigns_v2.sqlite    (116 KB, 1.5K rows)\n```\n\nThe server works with whatever datasets are present. Missing datasets degrade gracefully — tools that need unavailable data return clear messages instead of errors.\n\n## Architecture\n\n- **Transport**: stdio (Claude Desktop / Claude Code) or streamable-http (MCP Inspector)\n- **Database**: Read-only `sqlite3` connections (`?mode=ro`) — no writes, ever\n- **Query safety**: All queries use parameterized SQL (`?` placeholders), result limits enforced server-side (max 1000 rows)\n- **Grid lookup**: 31.7K Maidenhead grids loaded into memory at startup (~2 MB) for instant lat/lon resolution\n- **Solar geometry**: Pure Python solar elevation computation (same algorithm as the IONIS training pipeline) — classifies endpoints as day/twilight/night for propagation context\n- **Cross-source queries**: Each SQLite database opened separately, results merged in Python with source labels\n\n## Testing with MCP Inspector\n\n```bash\nionis-mcp --transport streamable-http --port 8000\n# Open http://localhost:8000/mcp in browser\n```\n\n## Related Projects\n\n| Repository | Purpose |\n|-----------|---------|\n| [ionis-validate](https://pypi.org/project/ionis-validate/) | IONIS model validation suite (PyPI) |\n| [IONIS Datasets](https://sourceforge.net/projects/ionis-ai/) | Distributed dataset files (SourceForge) |\n\n## License\n\nGPL-3.0-or-later\n\n## Citation\n\nIf you use the IONIS datasets in research, please cite:\n\n> Beam, G. (KI7MT). *IONIS: Ionospheric Neural Inference System — HF Propagation Prediction Datasets.* SourceForge, 2026. https://sourceforge.net/projects/ionis-ai/\n",
  "bytes": 8484,
  "sha": "71eed2a4ac200edc9124fce293201c09b5ec6d3fe7a463a710e2c0dea01c06c5",
  "repo_slug": "ionis-ai/ionis-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ionis_ai_ionis_mcp_965e9d71/readme"
}