ionis-mcp

ionis-mcp

通过任何兼容 MCP 的 AI 助手，使用 IONIS-AI 数据集分析 HF 无线电传播情况——这些数据集包含 1.75 亿多条聚合信号，源自 2005—2026 年间 140 亿条 WSPR、RBN、竞赛、DXpedition 和 PSK Reporter 观测记录。

这是 qso-graph 项目的一部分。无需身份验证。 数据集只需下载一次（参见数据集）。

安装

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

也可以使用 pip 安装：pip install ionis-mcp。

工具

工具	说明	关键参数
list_datasets	可用数据集及其行数和文件大小	—
query_signatures	按来源、波段、网格、小时和月份筛选信号	source, band, tx_grid, rx_grid, hour, month
band_openings	某条路径在一个波段上的逐小时传播概况	tx_grid, rx_grid, band
path_analysis	分析一条路径在所有波段、小时、月份和来源中的情况	tx_grid, rx_grid, source
solar_correlation	按 SFI 区间分析太阳通量对传播的影响	band, tx_grid, rx_grid
grid_info	解码 Maidenhead 网格并计算太阳高度角	grid, hour, month
compare_sources	跨数据集对比（WSPR、RBN、竞赛和 PSKR）	tx_grid, rx_grid, band
dark_hour_analysis	按太阳几何位置分析路径：两端白昼、跨越晨昏线、两端黑夜	band, hour, month
solar_history	查询指定日期范围内的历史太阳指数	start_date, end_date, resolution
band_summary	波段概况：逐小时分布、常见网格对和距离	band, source
current_conditions	实时预报：SFI、Kp、太阳风、波段展望、POTA/SOTA 建议	qth_grid
get_version_info	服务版本及上游规范版本（集群身份验证）	—

什么是 IONIS-AI？

IONIS-AI 是一个用于预测 HF（短波）无线电传播情况的开源机器学习系统。其数据集整理自全球最大的业余无线电遥测网络，并以 SQLite 文件形式发布在 SourceForge 上。ionis-mcp 可让助手基于这些数据集回答传播问题，无需编写 SQL。

来源	信号数	原始观测记录	SNR 类型	年份
WSPR	93.6M	10.9B 个信标报告	测量值（-30 至 +20 dB）	2008-2026
RBN	67.3M	2.3B 个 CW/RTTY 报告	测量值（8-29 dB）	2009-2026
CQ Contests	5.7M	234M 个 SSB/RTTY QSO	锚定值（+10/0 dB）	2005-2025
DXpeditions	260K	3.9M 条稀有网格路径	测量值	2009-2025
PSK Reporter	8.4M	514M+ 个 FT8/WSPR 报告	测量值（-34 至 +38 dB）	2026 年 2 月起
Solar Indices	—	77K 条每日/每 3 小时记录	SFI、SSN、Kp、Ap	2000-2026
DSCOVR L1	—	23K 个太阳风样本	Bz、速度、密度	2026 年 2 月起

所有信号表都采用相同的 13 列架构（tx_grid、rx_grid、band、hour、month、median_snr、spot_count、snr_std、reliability、avg_sfi、avg_kp、avg_distance、avg_azimuth），可直接用于跨来源分析。

数据集

# 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

就是这么简单。ionis-download 和 ionis-mcp 使用相同的默认数据目录，无需设置环境变量。

默认数据目录

平台	位置
Linux / macOS	~/.ionis-mcp/data/
Windows	%LOCALAPPDATA%\ionis-mcp\data\

使用自定义路径覆盖：

# 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

下载单个数据集

# 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

如果下载中断（连接断开、按下 Ctrl-C），再次运行相同命令即可：它会从中断处继续。短暂的网络错误会自动重试。大小单位为 MB 和 GB（1 MB = 1,000,000 字节）。

数据目录结构

~/.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)

服务可以使用现有的任何数据集。缺少数据集时会优雅降级——需要不可用数据的工具会返回清晰的提示，而不是报错。

快速开始

配置 MCP 客户端

ionis-mcp 可与任何兼容 MCP 的客户端配合使用。添加服务配置并重启即可。工具会自动显示。

如果将数据下载到了自定义位置，请在以下任一配置中添加 "env": { "IONIS_DATA_DIR": "/path/to/data" }。

Claude Desktop

添加到 claude_desktop_config.json（macOS 上为 ~/Library/Application Support/Claude/，Windows 上为 %APPDATA%\Claude\）：

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

Claude Code

添加到 .claude/settings.json：

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

ChatGPT Desktop

ChatGPT 通过 OpenAI Agents SDK 支持 MCP。在“设置”>“应用与连接器”下添加，或在 Agent 定义中配置：

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

Cursor

添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

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

VS Code / GitHub Copilot

添加到工作区中的 .vscode/mcp.json：

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

Gemini CLI

添加到 ~/.gemini/settings.json（全局）或 .gemini/settings.json（项目级）：

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

如果是通过 pip 安装的？在以上任一配置中使用 "command": "ionis-mcp"。

提问

“从 Idaho 到 Europe，什么时候 20m 频段开放？”

“太阳通量如何影响 15m 频段的传播？”

“显示 03z 时两端站点都处于黑暗中的 10m 路径”

“比较 20m FN31 到 JO51 的 WSPR 和 RBN 观测数据”

“当前的频段状况如何？我准备去参加 POTA。”

“2026 年 2 月地磁风暴期间的太阳状况如何？”

架构

• 传输：stdio（Claude Desktop / Claude Code）或 streamable-http（MCP Inspector）
• 数据库：只读 sqlite3 连接（?mode=ro）——绝不写入
• 查询安全性：所有查询都使用参数化 SQL（? 占位符），并在服务端强制限制结果数量（最多 1000 行）
• 网格查询：启动时将 31.7K 个 Maidenhead 网格加载到内存中（约 2 MB），以便即时解析经纬度
• 太阳几何：使用纯 Python 计算太阳高度（与 IONIS-AI 训练流水线采用相同算法）——将端点分类为白昼／晨昏／夜间，为传播分析提供背景信息
• 跨数据源查询：分别打开每个 SQLite 数据库，在 Python 中合并结果并标注数据源

MCP Inspector

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

然后在 http://localhost:8000/mcp 打开 MCP Inspector。

开发

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

相关项目

仓库	用途
ionis-validate	IONIS-AI 模型验证套件（PyPI）
IONIS-AI datasets	分发的数据集文件（SourceForge）

许可证

GPL-3.0-or-later

引用

如果您在研究中使用 IONIS-AI 数据集，请引用：

Beam, G. (KI7MT). IONIS：电离层神经推理系统 — HF 传播预测数据集。 SourceForge，2026 年。https://sourceforge.net/projects/ionis-ai/