What it does
WSJT-X has no API where you send a request and get an answer back. It broadcasts its state over UDP in messages such as Status, Decode, QSOLogged and Heartbeat. It also accepts a small set of control messages. wsjtx-mcp runs a UDP listener in the background that reads each datagram as it arrives. It keeps the latest status, a buffer of decodes and the completed QSOs. You read those, and you send WSJT-X control messages.
This has some consequences. UDP cannot change the dial frequency. You can read the dial from Status, and configure can set the mode, sub-mode, Rx DF and T/R period. To QSY you use rig control: Hamlib, CAT or the WSJT-X window. You can start and halt Tx, but you cannot turn Enable Tx on or off. A transmission starts when you answer a CQ with reply, or when you use free_text with send=true. transmit halt stops it. The Enable Tx, Auto Seq, Call 1st and Hold Tx Freq checkboxes can only be set in the WSJT-X window.
So wsjtx-mcp works well for search and pounce and is not well suited to RUN. The API is built to answer CQ and QRZ decodes, so search and pounce can be fully automated. To call CQ over and over, you need the Enable Tx checkbox in the WSJT-X window, or a free_text CQ sent again each period.
The protocol is schema 3 / Qt_5_4. It has not changed from WSJT-X 2.1 through 3.x. The server was tested live against WSJT-X 3.0.2.
wsjtx-mcp is experimental. It will not transmit until you set your callsign, and you remain the operator in command. Read the Safety section before you set the callsign.
Features and benefits
| Feature | What it gives you |
|---|---|
| UDP listener model | A background listener keeps the latest status, a decode buffer and the completed QSOs. You read that state instead of querying WSJT-X. |
| Decode and log buffers | Read, drain (poll for new decodes), clear or replay the decode stream. Completed QSOs are kept from QSOLogged and LoggedADIF, ready to pass to N3FJP. |
| Reply with Auto Seq | A reply is equivalent to double-clicking a CQ. With Auto Seq on, WSJT-X sequences the whole exchange to QSOLogged with no further calls. With Auto Seq off, it starts only the first transmission. |
| Free text | Set the Tx5 free-text message. send=true keys the radio and is callsign gated. |
| Halt-only transmit | The transmit tool only stops a transmission (halt or halt_auto). UDP has no command for Enable Tx. A transmission starts only through the callsign-gated reply or free_text with send=true. |
| Callsign transmit gate | With WSJTX_CALLSIGN blank the server is receive-only and refuses every message that would start a transmission. Halt and all reads still work. |
| Configure without dial frequency | Set the mode, sub-mode, Rx DF, T/R period, frequency tolerance, DX call and grid. The dial frequency is set by rig control: Hamlib, CAT or the WSJT-X window. |
| Window and station control | Clear the Band Activity and Rx Frequency windows, color or clear a callsign, override the Maidenhead grid, switch to a named configuration, set a Fox/Hound annotation. |
| Multicast coexistence | Set WSJTX_MULTICAST to join a multicast group, so JTAlert, GridTracker or N1MM can listen alongside this server. |
| Instance targeting | When several copies of WSJT-X broadcast, WSJTX_INSTANCE picks one by its Id. Control replies go back to the address each datagram came from. |
| Remote host | Sandboxed MCP clients can only reach loopback addresses. mcp-host-bridge install wsjtx --to <rig-host> carries the connection across the LAN. Then set WSJTX_PORT=2238. |
| Any message by name | wsjtx_call builds and sends any message type by name. The transmit gate still applies. |
| Standard-library codec | The protocol codec uses only Python's standard library and covers all 17 WSJT-X message types. Its unit tests run against fixed byte sequences, so they do not need a running WSJT-X. |
How it works
In WSJT-X, set Settings → Reporting → UDP Server to the host running this server, port 2237. To allow control, turn on Accept UDP requests. It is off by default. Reading decodes and status works without it.
Normally only one program on a computer can listen on UDP port 2237. If JTAlert, GridTracker or N1MM already use it, you have three choices. Point WSJT-X's secondary UDP server at this server. Use a multicast group so several programs can listen at once. Or run this server on a different computer.
To reach WSJT-X on another computer, install mcp-host-bridge on the computer that runs this server with mcp-host-bridge install wsjtx --to <rig-host>. Then set WSJTX_PORT=2238. Sandboxed MCP clients can only reach loopback addresses, so the bridge carries the connection across the LAN.
Ask it
Answering a CQ puts the station on the air. With WSJTX_CALLSIGN blank, the server refuses the request. You remain the control operator under Part 97. Stay where you can intervene, and say "stop" to halt.
Tools
| Tool | Kind | What it does |
|---|---|---|
status | observe | Latest Status snapshot, and the health of the listener and of each WSJT-X instance. |
diagnostics | observe | Host and network details, whether the UDP port is bound, datagram counts, and whether the transmit gate is open. |
decodes | observe/nudge | read, drain (poll for new decodes), clear_local and replay for the received decodes. |
log | observe | Completed QSOs buffered from QSOLogged and LoggedADIF, ready to pass to N3FJP. |
reply | transmit | Answer a buffered CQ or QRZ decode. When "Auto Seq" is on, WSJT-X sequences the rest of the QSO. |
free_text | transmit if send | Set the Tx5 free-text message. send=true keys the radio. |
transmit | control | halt or halt_auto stops a transmission. UDP cannot enable Tx. |
configure | control | Mode, sub-mode, Rx DF, T/R period, frequency tolerance, DX call and grid. Not the dial frequency. |
clear | control | Clear the Band Activity and Rx Frequency windows. |
highlight | control | Color or clear a callsign in Band Activity. |
location | control | Override the session Maidenhead grid. |
switch_config | control | Switch to a named WSJT-X configuration. |
annotate | control | Set a Fox/Hound sort-order annotation for a DX call. Mainly for DXpeditions. |
wsjtx_call | escape hatch | Build and send any message type by name. The transmit gate still applies. |
Settings
| Variable | Default | Purpose |
|---|---|---|
WSJTX_HOST | 127.0.0.1 | UDP address to bind and listen on. |
WSJTX_PORT | 2237 | WSJT-X UDP Server port. |
WSJTX_CALLSIGN | empty | Operator callsign. This is the only transmit gate. Blank means receive-only. |
WSJTX_MULTICAST | off | Optional multicast group to join, so other programs can listen to WSJT-X at the same time. |
WSJTX_INSTANCE | auto | Target a specific WSJT-X Id when several instances broadcast. |
Host and port are where this server listens. Control replies go back to the address each datagram came from.
Safety
The callsign is the only transmit gate, as in fldigi-mcp. With WSJTX_CALLSIGN blank the server is receive-only. It refuses reply, free_text with send=true, and any keying message sent through wsjtx_call. Halt, clear, configure, highlight, location, replay and all reads always work. None of them put you on the air, and halt takes you off. The client's tool permission prompt asks you to approve each transmission. status also shows WSJT-X's own Tx Watchdog and the Tx Enabled and Transmitting flags, as further safety signals. If you operate under Part 97 automatic or remote control, that is your responsibility as the operator. Make sure the station identifies and that a control operator can intervene.
Documents
- wsjtx-mcp guide, built from the project documents
- WSJT-X UDP message reference: WSJTX-API (PDF) · WSJTX-API (Markdown) · machine-readable spec
- INSTALL · REMOTE-HOST · README · CHANGELOG
- PyPI · GitHub repository