Wsjtx Mcp

io.github.sbrunner-atxPublished by GitHub account sbrunner-atxv0.1.3Updated Oct 24, 2026

Operate WSJT-X (FT8/FT4/WSPR) from MCP clients over its UDP message protocol.

VerifiedSTDIODesktop onlyDeveloper ToolsCommunication & Collaboration

Overview

AI-generated overview

Lets an assistant read WSJT-X FT8/FT4/WSPR status and decodes and, with a callsign set, answer CQs and key the radio.

What you can do
Runs a background UDP listener on the WSJT-X message protocol and exposes tools to read the latest Status snapshot, buffered decodes, and completed QSOs. Control tools set mode, sub-mode, Rx DF, T-R period, DX call and grid, clear or highlight Band Activity, override the grid, switch configurations, and halt transmission. Transmit tools answer a buffered CQ/QRZ decode or send a free-text message, and an escape hatch sends arbitrary message types by name.
When to use it
Use it for search-and-pounce weak-signal operating from an MCP client such as Claude Desktop, or to feed completed QSOs into a logging workflow. It suits reading decodes and status passively, and answering CQs hands-free when WSJT-X Auto Seq is enabled. It is a poor fit for driving a repeating call-CQ (RUN) cycle or for dial-frequency control.
Requirements
Local process on the user's machine (PyPI package wsjtx-mcp, stdio), desktop only. Needs WSJT-X 2.1 through 3.x with Settings, Reporting, UDP Server pointed at the host and port this server listens on (default 127.0.0.1:2237), and Accept UDP requests enabled for control. Configuration uses WSJTX_HOST, WSJTX_PORT, WSJTX_CALLSIGN, WSJTX_MULTICAST and WSJTX_INSTANCE. No authentication declared.
Before you install
Transmit is gated only by WSJTX_CALLSIGN; leaving it blank makes the server receive-only and it refuses transmit-initiating messages. With a callsign set, reply, free_text with send=true, and wsjtx_call can key the radio, so per-transmit approval and WSJT-X's Tx Watchdog matter. Operating under automatic or remote control is the operator's responsibility. Only one process can normally own UDP 2237, so check for JTAlert, GridTracker or N1MM conflicts.

Installation

In SourceWeft

  1. Open Wsjtx Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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).
  • n3fjp-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.

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 start and halt Tx, but cannot toggle "Enable Tx". Transmission is started by answering a CQ (reply) or by free_text with send=true, and stopped by transmit halt. There is no UDP command for the "Enable Tx", "Auto Seq", "Call 1st", or "Hold Tx Freq" checkboxes — those stay UI settings.
  • reply gives hands-free QSOs only when WSJT-X's "Auto Seq" is on. A reply is equivalent to double-clicking a CQ; with Auto Seq enabled (the usual FT8/FT4 default) WSJT-X then sequences the whole exchange to QSOLogged with no further calls. With Auto Seq off, reply starts only the first transmission.
  • Best for search-and-pounce, weak for RUN. The API is built to answer CQs (and only CQ/QRZ decodes), so S&P is fully automatable. It has no clean way to drive a repeating call-CQ (RUN) cycle — that needs WSJT-X's own "Enable Tx", or a free_text CQ re-sent each period.

Requirements

  • WSJT-X 2.1 through 3.x — the UDP message protocol is schema 3 / Qt_5_4 and has been stable across those releases (verified live against WSJT-X 3.0.2).
  • 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

VariableDefaultPurpose
WSJTX_HOST127.0.0.1UDP address to bind/listen on.
WSJTX_PORT2237WSJT-X UDP Server port.
WSJTX_CALLSIGN(empty)Operator callsign — the single transmit gate. Blank = receive-only.
WSJTX_MULTICAST(off)Optional multicast group to join (coexist with other UDP consumers).
WSJTX_INSTANCE(auto)Target a specific WSJT-X Id when several instances broadcast.

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

Tools

ToolKindWhat it does
statusobserveLatest Status snapshot + listener/instance health.
diagnosticsobserveHost/network + bind status + datagram counts + gate state.
decodesobserve/nudgeread / drain (poll new) / clear_local / replay. The RX plane.
logobserveBuffered completed QSOs (QSOLogged + LoggedADIF) → feed N3FJP.
replytransmitAnswer a buffered CQ/QRZ decode (auto-sequences the QSO when WSJT-X "Auto Seq" is on).
free_texttransmit if sendSet the Tx5 free-text message; send=true keys the radio.
transmitcontrolhalt / halt_auto — stop transmitting (UDP can't enable Tx).
configurecontrolMode/sub-mode/Rx DF/T-R period/freq-tol/DX call+grid. No dial freq.
clearcontrolClear the Band Activity / Rx Frequency windows.
highlightcontrolColour or clear a callsign in Band Activity.
locationcontrolOverride the session Maidenhead grid.
switch_configcontrolSwitch to a named WSJT-X configuration.
annotatecontrolSet a Fox/Hound sort-order annotation for a DX call (niche, DXpedition).
wsjtx_callescape hatchBuild & send any message type by name (gate still applies).

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. To reach a WSJT-X on another machine, install the mcp-host-bridge tool (mcp-host-bridge install wsjtx --to <rig-host>) and set WSJTX_PORT=2238 — sandboxed MCP clients reach only loopback, and the bridge does the LAN hop. See docs/REMOTE-HOST.md.

Development

sh
uv syncuv 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)

Source: README.md at commit 021c4ec

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.3LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts