wsjtx-mcp

wsjtx-mcp

一个用于控制 WSJT-X（FT8/FT4/JT65/MSK144/Q65/WSPR……）的 MCP 服务，可供 Claude Desktop 和 MCP Inspector 等 MCP 客户端使用。

它是业余无线电“操作 → 记录”三件套中的弱信号部分：

• fldigi-mcp — 通过 fldigi（XML-RPC）操作各种数字模式。
• n3fjp-mcp — 将 QSO 记录到 N3FJP（TCP API）。
• wsjtx-mcp （本项目） — 通过 WSJT-X（UDP 消息协议）操作 FT8/FT4 弱信号通信。

⚠️ 实验性（v0.1）。 发射功能受你的呼号限制，并且由操作员掌控。请阅读发射安全部分。

有何不同

WSJT-X 不提供请求/响应 API。它会通过 UDP 广播状态（Status、Decode、QSOLogged、Heartbeat……），并接受少量传入的控制消息。因此，本服务会运行一个后台 UDP 监听器，持续解析数据报并保存最新状态、解码缓冲区和已完成的 QSO；你可以读取这些信息，并通过控制消息向 WSJT-X 发送指令。

请预先了解以下事项：

• 无法通过 UDP 控制拨盘频率。 你可以从 Status 读取拨盘频率，也可以通过 configure 设置模式/子模式/Rx DF/T-R 周期，但 QSY 属于电台控制范畴（Hamlib/CAT 或 UI），不属于本服务的功能。
• 可以启动和停止发射，但无法切换“Enable Tx”。 通过应答 CQ（reply），或使用 send=true 的 free_text 来启动发射；通过 transmit halt 来停止发射。UDP 没有用于控制“Enable Tx”、“Auto Seq”、“Call 1st”或“Hold Tx Freq”复选框的命令——这些仍是 UI 设置。
• 只有在 WSJT-X 开启“Auto Seq”时，reply 才能实现免手动操作的 QSO。 reply 等同于双击 CQ；启用 Auto Seq（FT8/FT4 的常见默认设置）后，WSJT-X 会自动完成整个交互流程并生成 QSOLogged，无需进一步调用。关闭 Auto Seq 时，reply 只会启动第一次发射。
• 最适合搜索并应答，不适合 RUN。 此 API 用于应答 CQ（且只处理 CQ/QRZ 解码），因此可将 S&P 完全自动化。它无法干净利落地驱动重复的呼叫 CQ（RUN）流程——这需要使用 WSJT-X 自带的“Enable Tx”，或每个周期重新发送 free_text CQ。

要求

• WSJT-X 2.1 至 3.x——UDP 消息协议为 schema 3 / Qt_5_4，这些版本中一直保持稳定（已通过 WSJT-X 3.0.2 实机验证）。
• 在 WSJT-X 中：Settings → Reporting → UDP Server
  • UDP Server = 运行本服务的主机（默认 127.0.0.1），端口 2237。
  • Accept UDP requests = ON，以允许控制（默认关闭）。无需开启此选项即可观察解码/状态；但要发送指令则必须开启。

安装（Claude Desktop）

从最新版本下载 wsjtx-mcp.mcpb，然后双击该文件，或将它拖到 Claude Desktop → Settings → Extensions。填写设置表单（呼号、主机、端口）。请参阅 docs/INSTALL.md。

配置

变量	默认值	用途
WSJTX_HOST	127.0.0.1	要绑定/监听的 UDP 地址。
WSJTX_PORT	2237	WSJT-X UDP Server 端口。
WSJTX_CALLSIGN	(empty)	操作员呼号——唯一的发射权限门槛。留空 = 仅接收。
WSJTX_MULTICAST	(off)	可选的多播组，用于与其他 UDP 消费者共存。
WSJTX_INSTANCE	(auto)	有多个 WSJT-X 实例广播时，指定目标 Id。

主机/端口指的是本服务的监听地址；控制回复会发送回每个数据报的来源地址。

工具

工具	类型	功能
status	观察	最新的 Status 快照，以及监听器/实例运行状况。
diagnostics	观察	主机/网络、绑定状态、数据报计数和门控状态。
decodes	观察/提示	read / drain（轮询新内容）/ clear_local / replay。接收平面。
log	观察	已缓冲的已完成 QSO（QSOLogged + LoggedADIF）→ 输入到 N3FJP。
reply	发射	回复已缓冲的 CQ/QRZ 解码（WSJT-X 开启「Auto Seq」时，会自动推进 QSO 序列）。
free_text	发射（若 send）	设置 Tx5 自由文本消息；send=true 会触发电台发射。
transmit	控制	halt / halt_auto — 停止发射（UDP 无法启用 Tx）。
configure	控制	模式/子模式/Rx DF/T-R 周期/频率容差/DX 呼号和网格。不含拨盘频率。
clear	控制	清除 Band Activity / Rx Frequency 窗口。
highlight	控制	在 Band Activity 中为呼号着色或清除颜色。
location	控制	覆盖会话的 Maidenhead 网格。
switch_config	控制	切换到指定名称的 WSJT-X 配置。
annotate	控制	为 DX 呼号设置 Fox/Hound 排序注释（小众功能，适用于 DXpedition）。
wsjtx_call	应急出口	按名称构建并发送任意消息类型（仍受门控约束）。

发射安全

呼号是唯一的发射门控，与 fldigi-mcp 完全相同。当 WSJTX_CALLSIGN 为空时，服务仅接收：它会拒绝所有发起发射的消息 —— reply、send=true 的 free_text，以及通过 wsjtx_call 发送的任何按键消息。transmit halt、clear、configure、 highlight、location、replay 和所有读取操作始终可用（它们不会让你发射；halt 会让你停止发射）。

除这道门控外：

• 每次发射的批准由 Claude Desktop 的工具权限提示提供 —— 请善用它来实现人在回路中的控制。
• WSJT-X 自带的 Tx Watchdog 和 status 中呈现的 Tx Enabled / Transmitting 标志 是额外的安全信号。
• 按照 Part 97 自动/远程控制方式操作，责任在于操作员：确保电台身份识别到位，并有能够介入的控制操作员。

与其他 UDP 工具同时运行

通常，一台主机上只能有一个进程占用 UDP 2237。如果 JTAlert、GridTracker 或 N1MM 已在使用它，可以将 WSJT-X 的辅助 UDP 服务端指向此处，使用 多播组（WSJTX_MULTICAST）让多个监听器共存，或在另一台主机上运行 此服务。要连接另一台机器上的 WSJT-X，请安装 mcp-host-bridge 工具 （mcp-host-bridge install wsjtx --to <rig-host>），并设置 WSJTX_PORT=2238 —— 沙盒化的 MCP 客户端只能访问 loopback，由桥接工具负责跨越 LAN。参见 docs/REMOTE-HOST.md。

开发

uv sync
uv run ruff check .
uv run pytest

协议编解码器仅使用标准库编写，并通过字节样例进行单元测试，因此测试无需运行 WSJT-X。smoke_test.py 可验证是否能以仅接收模式连接到正在运行的 WSJT-X。经实地测试的消息参考文档位于 docs/WSJTX-API.md。

许可证

MIT © 2026 Stefan Brunner (AE5VG)