wsjtx-mcp

An MCP server that controls WSJT-X (FT8/FT4/JT65/MSK144/Q65/WSPR…) from MCP clients such as Claude Desktop and the MCP Inspector.

It is the weak-signal leg of an "operate → log" trio for amateur radio:

• fldigi-mcp — operate broad digital modes via fldigi (XML-RPC).

• contest-mcp — log QSOs to N3FJP (TCP API).

• wsjtx-mcp (this one) — operate the FT8/FT4 weak-signal world via WSJT-X (UDP message protocol).

⚠️ Experimental (v0.1). Transmit is gated behind your callsign and you keep the operator in command. Read the Transmit safety section.

How it is different

WSJT-X does not offer a request/response API. It broadcasts state over UDP (Status, Decode, QSOLogged, Heartbeat, …) and honours a small set of inbound control messages. So this server runs a background UDP listener that continuously parses datagrams and keeps the latest status, a buffer of decodes, and completed QSOs — you read those, and nudge WSJT-X with control messages.

Two consequences worth knowing up front:

• No dial-frequency control over UDP. You can read the dial frequency from Status, and set mode/sub-mode/Rx DF/T-R period via configure, but QSY is a rig-control concern (Hamlib/CAT or the UI), not this server.

• You can halt Tx but not "Enable Tx". Transmission is started by answering a CQ (reply) or by free_text with send=true; it is stopped by transmit halt. There is no UDP command to press "Enable Tx".

Related MCP server: MultiViewer

Requirements

• WSJT-X 2.x (verified against the 2.7 message schema, schema 3 / Qt_5_4).

• In WSJT-X: Settings → Reporting → UDP Server

  • UDP Server = the host running this server (default 127.0.0.1), port 2237.

  • Accept UDP requests = ON to allow control (it is OFF by default). Observing decodes/status works without it; commanding does not.

Install (Claude Desktop)

Download the wsjtx-mcp.mcpb from the latest release and double-click it, or drag it onto Claude Desktop → Settings → Extensions. Fill in the settings form (callsign, host, port). See docs/INSTALL.md.

Configuration

Host/port are where this server listens; control replies are sent back to the address each datagram arrived from.

Tools

Transmit safety

The callsign is the single transmit gate, exactly as in fldigi-mcp. With WSJTX_CALLSIGN blank the server is receive-only: it refuses every transmit-initiating message — reply, free_text with send=true, and any keying message via wsjtx_call. transmit halt, clear, configure, highlight, location, replay, and all reads are always available (they don't put you on the air; halt takes you off).

Beyond that gate:

• Per-transmit approval comes from the Claude Desktop tool-permission prompt — lean on it for human-in-the-loop control.

• WSJT-X's own Tx Watchdog and the Tx Enabled / Transmitting flags (surfaced in status) are extra safety signals.

• Operating under Part 97 automatic/remote control is the operator's responsibility: ensure station identification and a control operator who can intervene.

Running alongside other UDP tools

Only one process can normally own UDP 2237 on a host. If JTAlert, GridTracker, or N1MM already consume it, either point WSJT-X's secondary UDP server here, use a multicast group (WSJTX_MULTICAST) so several listeners coexist, or run this server on a different host. See docs/REMOTE-HOST.md for reaching a WSJT-X on another machine (it requires a small UDP forwarder because sandboxed MCP clients reach only loopback).

Development

uv sync
uv run ruff check .
uv run pytest

The protocol codec is pure standard library and unit-tested against byte fixtures, so the tests need no running WSJT-X. A smoke_test.py proves a live WSJT-X is reachable receive-only. The field-tested message reference lives in docs/WSJTX-API.md.

License

MIT © 2026 Stefan Brunner (AE5VG)