rigctlmcp (Zappatta)

Rigctl MCP服务器

](https://badge.fury.io/py/rigctl-mcp) 

一种模型上下文协议（MCP）服务器，用于通过Hamlib-rigctl协议控制软件定义无线电（SDR）应用程序。

概述

此MCP服务器为AI助手提供了控制无线电接收器和SDR++、GQRX等SDR软件以及其他兼容Hamlib的应用程序的能力。它实现了rigctl网络协议，允许频率调谐、模式选择和记录控制。

特性

• 频率控制：以Hz为单位设置和查询射频
• 模式控制：选择解调模式（FM、WFM、AM、USB、LSB、CW、DSB、RAW）
• 录音控制：开始/停止录音
• 快速调频调谐：调频广播电台（88-108MHz）调谐便利工具
• 定时录制：在指定的持续时间内录制音频，并自动启动/停止

支持的应用程序

任何支持Hamlib rigctl网络协议的应用程序：

• SDR++ -流行的跨平台SDR应用
• GQRX -Linux SDR接收器
• CubicSDR -跨平台SDR应用
• rigctld -硬件无线电的Hamlib网络守护进程

安装

使用uvx（推荐）

uvx rigctl-mcp

使用pip

pip install rigctl-mcp

来源（开发）

git clone https://github.com/Zappatta/rigctlmcp.git
cd rigctlmcp
pip install -e .

设置

SDR++配置

1. 开放SDR++
2. 启用 Rigctl服务器 模块管理器中的模块
3. 配置rigctl设置：

- 端口：4532（默认Hamlib端口） - 绑定地址: - 0.0.0.0 如果使用Docker - 127.0.0.1 如果在本地运行

1. 连接到您的SDR设备

Docker说明

如果在Docker中运行MCP服务器，rigctl服务器必须绑定到 0.0.0.0 以便从容器中取出。使用 host.docker.internal:4532 从Docker内部进行连接。

用法

运行MCP服务器

# Using uvx
uvx rigctl-mcp

# With options
uvx rigctl-mcp --host 192.168.1.50 --port 4532 --auto-connect

# If installed via pip
rigctl-mcp

CLI选项

服务器通过stdio通信，可以与MCP兼容的客户端集成。

桌面客户端配置

添加到MCP客户端配置中：

{
  "mcpServers": {
    "rigctl": {
      "command": "uvx",
      "args": ["rigctl-mcp", "--auto-connect"]
    }
  }
}

可用工具

连接管理

连接

连接到rigctl服务器。

参数：

• host （可选）：服务器地址（默认：“localhost”）
• port （可选）：服务器端口（默认值：4532）

例子：

{
  "host": "localhost",
  "port": 4532
}

断开

断开与rigctl服务器的连接。

获取状态

获取当前连接状态。

频率控制

set_频率

设置无线电频率，单位为Hz。

参数：

• frequency_hz （必填）：频率（Hz）

例子：

{
  "frequency_hz": 100000000
}

将频率设置为100 MHz。

get_频率

获取当前的无线电频率。

退货： 频率单位为Hz和MHz。

调频电台

快速调谐到调频广播电台（88-108MHz）。

参数：

• frequency_mhz （必填）：FM频率，单位为MHz（例如88.5、101.1）
• set_wfm_mode （可选）：自动设置WFM模式（默认值：true）

例子：

{
  "frequency_mhz": 88.0,
  "set_wfm_mode": true
}

模式控制

set_mode

设置解调模式和带宽。

参数：

• mode （必填）：FM、WFM、AM、USB、LSB、CW、DSB或RAW
• bandwidth （可选）：带宽（Hz）（0表示自动）

例子：

{
  "mode": "WFM",
  "bandwidth": 200000
}

get_mode

获取当前解调模式和带宽。

录音控制

开始记录

开始录制音频。文件将保存到应用程序的录制目录中。

停止记录

停止录制音频。

录音_音频

方便的工具，可以在指定的持续时间内进行调谐、设置模式和录制。

参数：

• frequency_hz （必填）：频率（Hz）
• mode （可选）：解调模式
• duration_seconds （必填）：录制时长（1-3600秒）

例子：

{
  "frequency_hz": 88000000,
  "mode": "WFM",
  "duration_seconds": 30
}

在WFM模式下记录88 MHz的30秒。

用法示例

调到调频电台

# Connect to rigctl
connect("host.docker.internal", 4532)

# Tune to 88.5 FM
tune_fm_station(88.5)

# Or manually:
set_frequency(88500000)
set_mode("WFM", 200000)

录制音频

# Quick recording (automatic tuning and timing)
record_audio(
    frequency_hz=101100000,
    mode="WFM",
    duration_seconds=60
)

# Manual recording control
set_frequency(88000000)
set_mode("WFM", 200000)
start_recording()
# ... wait ...
stop_recording()

查询当前设置

# Get current frequency
get_frequency()
# Returns: "Current frequency: 88000000 Hz (88.000 MHz)"

# Get current mode
get_mode()
# Returns: "Current mode: WFM, bandwidth: 200000 Hz"

Rigctl协议

此服务器实现了Hamlib rigctl网络协议。关键命令：

• F -设置频率（Hz）
• f -获取频率
• M -设置模式和带宽
• m -获取模式
• AOS / \recorder_start -开始录制
• LOS / \recorder_stop -停止录制

测试（开发）

包含用于开发的测试脚本：

# Clone and install for development
git clone https://github.com/Zappatta/rigctlmcp.git
cd rigctlmcp
pip install -e .

# Test connection and basic commands
python scripts/tests/test_rigctl.py

# Test FM tuning
python scripts/tests/test_fm.py

# Test recording
python scripts/tests/test_recording.py

故障排除

连接被拒绝

问题：无法连接到rigctl服务器

解决方案:

• 验证SDR++（或其他应用程序）是否正在运行
• 检查rigctl服务器模块是否已启用
• 验证端口是否正确（默认值：4532）
• 对于Docker：确保绑定地址为 0.0.0.0
• 尝试： ss -tln | grep 4532 检查端口是否正在侦听

命令不起作用

问题：命令返回错误或不起作用

解决方案:

• 检查应用程序日志是否有错误
• 验证SDR是否已连接并在应用程序中工作
• 某些命令可能并非所有应用程序都支持
• 使用手动尝试该命令 telnet localhost 4532

录制目录

录音将保存到应用程序配置的录音目录中：

• SDR++：检查设置→ 录制
• GQRX：检查文件→ 保存选项
• 默认位置因平台而异

技术细节

协议

在TCP套接字上使用Hamlib rigctl协议。命令是ASCII文本，响应以换行符结尾。

线程

套接字操作是同步的，但MCP服务器在异步上下文中运行。长时间运行的操作（如定时录制）使用 asyncio.sleep().

错误处理

• 连接错误返回用户友好的消息
• 无线电应用程序验证无效的频率/模式
• 会报告录制错误，但不会断开客户端连接

参考文献

• Hamlib Rigctl文档
• Hamlib网络协议
• SDR++Rigctl实现
• 模型上下文协议