fldigi-mcp

fldigi-mcp

一个用于控制 fldigi 的 MCP 服务。fldigi 是一款广受欢迎的业余无线电数字调制解调器应用，可通过 Claude Desktop 等支持 MCP 的客户端进行控制。

fldigi 内置 XML-RPC 控制接口。fldigi-mcp 连接到该接口，并将整个 API 封装为一组按逻辑分组的 MCP 工具，让助手能够读取电台状态，并通过日常语言控制调制解调器、无线电设备、日志和发射机。

状态： Beta 版。支持信号搜寻（从接收音频中查找电台、为其命名并调谐，0.2.0）、完整 API 覆盖（通过命名操作访问 fldigi 的全部 174 个 XML-RPC 方法，并由测试强制验证）、呼号门控发射，以及可选的实验性频段指引功能。支持当前版本 fldigi 4.2.13，并已于 2026-09-09 进行实时验证。

📻 经实地测试的 fldigi XML-RPC API 参考（免费社区资源）

构建此服务需要梳理 fldigi 的整个 XML-RPC 接口，并针对实时运行的版本验证每个方法——因此我们将全部内容整理成文并免费分享，无论你是否使用此 MCP 服务：

• docs/fldigi-api.md — 简洁、完整、易于阅读的参考文档，按命名空间组织，包含传输详情、类型、示例、发射安全章节以及实测注意事项。
• docs/fldigi-api.pdf — 相同内容的可打印 PDF。
• docs/fldigi-api-spec.md — 简明、机器可读的全部 174 个方法目录（参数、返回类型、读／写／发射键控）。

已于 2026-09-09 通过 fldigi.list 对 fldigi 4.2.13 进行实时验证（方法列表与 4.2.11 相同，首次验证日期为 2026-06-23）。它比公开 Wiki 更完整、更新也更及时（记录了 Wiki 未提及的方法，例如 TxID，并标记了已弃用的方法）。**这是一个独立项目，与 fldigi / W1HKJ 项目无关联。**欢迎通过问题／PR提交修正。

亮点

• 完整控制 — fldigi 4.2.13 的全部 174 个 XML-RPC 方法都可以通过分组工具中的命名操作访问（每个操作单独授权；全部 22 个工具列于工具下）； 如果已发布目录中的方法未接入，或参数类型与 fldigi 的签名不符，tests/test_coverage.py 就会导致构建失败。对于较新版本可能新增的方法，仍可使用 fldigi_call 备用入口。
• 默认安全 — 呼号是唯一的发射门控。未配置呼号时，电台仅可接收；无法键控发射机。
• 名称与 fldigi 一致 — 工具和操作沿用 fldigi 自身的 API 命名空间和屏幕标签（Op Mode、AFC、SQL、Rev、Lock、RxID/TxID、T/R）。
• 无脆弱依赖 — 使用 Python 标准库中的 xmlrpc.client 与 fldigi 通信。运行时唯一的第三方依赖是 MCP SDK 和 PyYAML（用于可选的频段规划数据）。

为什么使用 XML-RPC（而不是第三方库）

fldigi 的 XML-RPC 接口是其官方、独立于操作系统的控制 API。本项目直接与其通信，而不依赖无人维护的封装库，从而将组件限制在 Python 标准库和 fldigi 自身的 API。

要求

要安装桌面扩展（.mcpb），你只需要：

• 正在运行的 fldigi（默认在 127.0.0.1:7362 启用其 XML-RPC 服务）。

Claude Desktop 的 uv 运行时会提供 Python 和依赖，因此终端用户无需自行安装 Python 或 uv。（该运行时目前标记为实验性，建议使用较新版本的 Claude Desktop。）

要从源代码进行开发，还需要 Python 3.10+ 和 uv（以及 Node.js，仅 MCP Inspector 需要）。

安装

最简单：一键式桌面扩展

从最新的 发布版本下载 fldigi-mcp.mcpb，然后在 Claude Desktop 中依次前往设置 → 扩展 → 高级设置 → 安装扩展…， 并选择该文件。 简短的设置表单会询问你的呼号（其他内容均有默认值）。 无需安装终端、Python 或 uv。

👉 如果你是新手，请按照简单的分步安装指南操作。 另请参阅安装与安全模型。

从源代码安装（开发）

git clone https://github.com/sbrunner-atx/fldigi-mcp.git
cd fldigi-mcp
uv sync

然后将其添加到 Claude Desktop 的配置中 （macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "fldigi": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/fldigi-mcp", "run", "fldigi-mcp"],
      "env": { "FLDIGI_CALLSIGN": "AE5VG" }
    }
  }
}

重启 Claude Desktop 并询问 “fldigi 的状态如何？”。省略 env 块即可仅运行接收功能。

使用 MCP Inspector 试用

uv run mcp dev src/fldigi_mcp/server.py

Signal Browser 补丁（patches/）——提议中，尚未合并

**状态：**已于 2026 年 9 月 11 日提交给 fldigi 维护者（w1hkj/fldigi issue 55）。 在合并之前，以下方法名称和字段均为提议，可能会有变化。

fldigi 的 Signal Browser 是左侧面板，可同时解码最多 30 个 PSK、RTTY 或 CW 电台，但它并未提供 XML-RPC API。patches/fldigi-4.2.13-browser-xmlrpc.patch 修改了四个文件（psk_browser.h/.cxx、viewpsk.cxx、xmlrpc.cxx），并添加了两个方法：browser.get_channels（返回 {channel, freq, active, text} 数组； 文本不裁剪，保留换行符，自上次清除以来累积）和 browser.clear。browser 工具和 signal_hunt method="browser" 会使用这些方法，并在 fldigi 未打补丁时说明这一点。 第二个补丁 patches/fldigi-4.2.13-rsid-hits.patch（基于第一个补丁应用）添加了 rsid.get_hits 和 rsid.clear：即检测器接受的 RSID 突发信号，以 {utc, mode, hz} 形式呈现。将 RSID 设置为仅通知后，fldigi 就能指出频段上的模式，而不会切换调制解调器；rsid 工具会读取该列表。这两个补丁均为提议，尚未合并。 已在 4.2.13 上测试（macOS，四个从 0 到 -26 dB 的合成 PSK31 电台：四个电台的信息均完整复制）。该补丁适用于 SourceForge 上 fldigi git HEAD，已准备好提交上游；在补丁合并之前，请使用该补丁从源代码构建 fldigi：

tar xf fldigi-4.2.13.tar.gz && cd fldigi-4.2.13
patch -p1 < /path/to/fldigi-mcp/patches/fldigi-4.2.13-browser-xmlrpc.patch
./configure --prefix=$HOME/.local/fldigi && make -j8 && make install

工具

每个工具对应一项权限，并接受一个 operation 参数。因此，例如“更改模式”无论底层运行哪种方法，都只算一项权限。

工具	控制范围（fldigi 区域）
status	快速快照：版本、模式、频率、收发、呼号、波段
diagnostics	主机／网络信息，用于排查连接问题（不连接 fldigi）
application	程序信息，以及启动／停止 fldigi 进程（fldigi.*）
modem	操作模式／调制解调器选择、载波、带宽、AFC 范围、Olivia
frequency	拨盘频率和瀑布图边带
controls	AFC、SQL、Rev、Lock、RxID、TxID、状态字段
transmit	收发、Tune、中止、禁用／启用发射、宏、发送 — 受呼号控制
rig	CAT 控制：模式、频率、带宽、陷波、QSY、电平表
log	日志簿／竞赛字段；ADIF 最新／全部记录
text	RX／TX 文本和数据流
spot	信号报告／PSK Reporter
wefax	WEFAX（气象传真）模式
navtex	NAVTEX／SitorB 模式
flmsg	flmsg（消息表单）互通
io	ARQ／KISS I/O 端口选择
legacy	fldigi 仍提供的已弃用方法，并列出各方法当前对应的等效方法
band_guidance	波段／常用频点建议（实验性）
signal_hunt	查找并识别接收器音频中的信号；为呼叫 CQ 的电台排序（实验性，需额外安装 [hunt]）
tune_to	将调制解调器和载波设为 signal_hunt 候选信号，仅接收
browser	fldigi 的 Signal Browser：解码器组保存的每个电台及其文本（需要应用 patches/ 中的 fldigi 补丁）
rsid	通带中听到的 RSID 突发、模式和频率，不切换调制解调器（需要应用 patches/ 中的 rsid-hits 补丁）
fldigi_call	应急入口 — 按名称调用任意方法，包括未来添加的方法

使用 application → list_methods 列出正在运行的构建所支持的所有方法。在 4.2.13 中，所有方法都会显示在一个分组中；如果更新版 fldigi 添加了此连接器尚未支持的方法，可使用 fldigi_call 调用。

配置

变量	默认值	用途
FLDIGI_HOST	127.0.0.1	fldigi XML-RPC 主机
FLDIGI_PORT	7362	fldigi XML-RPC 端口
FLDIGI_CALLSIGN	(空)	操作员呼号。唯一的发射门控项 — 设置此项即可启用发射；留空则电台保持仅接收状态
FLDIGI_BAND_GUIDANCE	off	实验性波段建议。设为 on 即可启用
FLDIGI_REGION	2	波段建议使用的 IARU 区域：1、2 或 3
FLDIGI_PATH	(自动)	fldigi 可执行文件的显式路径（用于 application launch）
FLDIGI_AUDIO_DEVICE	(系统默认)	信号搜索所监听的输入设备：fldigi 正在使用的设备名称（或部分名称），例如 iMic
FLDIGI_HUNT_URL	(空)	与 fldigi 一同运行的 fldigi-mcp-tap 的 URL，例如 http://127.0.0.1:7365，用于此服务无法打开声卡时（沙盒环境，或 fldigi 在另一台机器上运行）。留空则监听本地输入设备

在打包的桌面扩展中，这些选项会显示为设置表单 — 大多数用户只需填写呼号。

发射安全

呼号是唯一的发射门控项。按键发射操作（transmit 的 tx/tune/run_macro/send、wefax／navtex 的发送操作，以及通过 fldigi_call 调用的任何按键发射方法）在未设置 FLDIGI_CALLSIGN 时都会被拒绝。留空时，电台保持仅接收状态。rx、abort 和 disable_tx 始终允许，因为它们会让电台退出发射状态。任何非空值都会被接受（俱乐部、活动、特殊纪念、便携式和国际呼号均可使用）。请参阅 docs/install-and-safety.md。

频段指导（实验性，默认关闭）

一项可选的辅助功能，用于建议某种模式通常使用的“联络频点”，并在频率超出数字模式频段范围时发出警告——只提供指导和默认值，不会强制限制。支持按地区区分（IARU R1/R2/R3），覆盖 160 m 至 70 cm。使用 FLDIGI_BAND_GUIDANCE=on 启用。启用后会添加 band_guidance 工具，并为 modem/frequency 的 set 操作添加辅助性的 guidance 字段。由于频段规划数据很难做到完全准确，此功能以实验性功能提供，且默认关闭。设计和数据说明：docs/band-guidance.md。

远程／分布式设置

fldigi 无需运行在同一台机器上。使用 FLDIGI_HOST/FLDIGI_PORT 指定服务器连接到 fldigi。fldigi 所在机器必须使用 --xmlrpc-server-address 0.0.0.0 启动，才能接受局域网连接；连接应限于可信局域网，或通过 SSH 隧道传输（XML-RPC 接口未进行身份验证）。

沙盒化的 MCP 客户端（例如 Claude Desktop）： 客户端运行的连接器处于沙盒中，只能访问 127.0.0.1，无法访问局域网地址——因此，即使 telnet 可以连接，填写正确的 fldigi 局域网 IP 也会超时。请在客户端计算机上使用独立的 mcp-host-bridge 中继（它知道 fldigi = 端口 7362），然后设置 FLDIGI_HOST=127.0.0.1：

pipx install mcp-host-bridge             # or download a binary from its releases
mcp-host-bridge install fldigi --to 192.168.1.50

使用 mcp-host-bridge status fldigi / uninstall fldigi 管理。该工具还可为 N3FJP（供同系列的 n3fjp-mcp 使用）及其他本地服务建立桥接。

技能

skills/ 目录包含 Agent 技能——根据实际空中操作提炼出的操作流程——并随代码仓库和 .mcpb 软件包一起提供：

• signal-hunting — 像操作员查看瀑布图那样，找到值得联络的电台：signal_hunt 根据每个信号的带宽和音调网格识别其模式（RTTY、CW、PSK、Olivia、MFSK、DominoEX、MT63；特征已与 sigidwiki.com 核对），为静止且正在呼叫 CQ 的信号排序；tune_to 设置调制解调器和载波；接收 20 秒文本即可确认。需要 pip install 'fldigi-mcp[hunt]'（numpy、sounddevice）和 Audio input device 设置；如果服务器未运行在接收机旁（沙盒环境或远程 fldigi），则在接收机旁运行 fldigi-mcp-tap，服务器通过 HTTP 向其请求数据（Signal-hunt tap URL）；如果没有音频，则回退为逐步调用 fldigi 的 search_up。已在 5 段已知模式录音上验证，5 段全部通过。仅接收。
• fldigi-operating — 正确处理 TX/RX 交接（通过 transmit → send 使用 ^r 返回接收状态，使用 abort 作为紧急停止按钮，绝不轮询 TX 缓冲区）、RX 缓冲区轮询规范（增量读取、禁止回显规则、重启检测），以及 CQ 循环参考流程。已在 ARRL Field Day 2026 期间经过实地验证。

fldigi-mcp 操作现场指南（PDF）介绍了这些技能，以及同系列 n3fjp-mcp 中配套的 contest-operating：技能概览、安装说明、为 AI 新手业余无线电爱好者准备的通俗易懂章节“你的首次操作——Claude 与业余无线电爱好者”、操作规范、特殊情况处理手册，以及根据 ARRL Field Day 2026 转录的操作示例。

如需在 Claude Code / Cowork 中使用，请将技能目录复制到 ~/.claude/skills/（或项目的 .claude/skills/）。

开发

uv sync
uv run ruff check .      # lint
uv run pytest            # tests (no running fldigi required)

测试套件覆盖频段规划逻辑以及操作映射／类型强制转换；无需运行中的 fldigi。

许可证

GPL-3.0-or-later © 2026 Stefan Brunner（AE5VG）

fldigi-mcp 是自由软件：你可以根据自由软件基金会发布的 GNU 通用公共许可证条款重新分发和／或修改它，可以选择使用第 3 版，或任何后续版本。它在 0.2.2 及之前版本采用 MIT 许可证；更改为 GPL-3.0-or-later（fldigi 本身使用的许可证）后，本项目便可以直接复用 fldigi 的代码，例如其多通道信号浏览器。通过 XML-RPC 与 fldigi 通信并不需要这样做；移植其解码器则需要。