io.github.qso-graph/jt-mcp

jt-mcp

Ask an AI app what WSJT-X is hearing. WSJT-X sends what it is doing and every decode to a UDP Server address; jt-mcp listens there and answers: who is calling CQ, and what kind of CQ (DX, POTA, a contest, a region), who has been heard and how well, what WSJT-X is tuned to, recent decodes and WSPR spots.

Read-only, permanently. jt-mcp never sends WSJT-X a message, so it cannot answer a call, key your transmitter or change a setting. No write, no PTT, no transmit control — a permanent constraint, not a first-version limit. The tests assert it against the source.

WSJT-X first, and WSJT-X defines the protocol. The UDP message definitions come from the WSJT-X project — Network/NetworkMessage.hpp, at the schema WSJT-X states — because the project that owns a definition is its authority. The code is qso-graph-lib's, the same that qso-graph-sim plays WSJT-X's messages with. JTDX, WSJT-Z and MSHV are supported where they work with those definitions, and where one does not, its difference is not implemented here. JS8Call, whose API is its own, follows WSJT-X.

This server was js8call-mcp until 2026-10-29. Part of the qso-graph project.

Install

uvx jt-mcp            # run it; nothing to install

Set up WSJT-X

In WSJT-X: File, Settings, Reporting, UDP Server: 127.0.0.1, port 2237 (WSJT-X's defaults). That is all jt-mcp needs when WSJT-X runs on the same PC.

Only one program can listen on a UDP port. If GridTracker, JTAlert or another logger already listens on 2237, give jt-mcp a different port (--udp-port) and point WSJT-X at that one.

Tools

Times are UTC. Several WSJT-X instances (two radios, two bands) are kept apart by the Id each sends, such as WSJT-X - FT-991A.

Questions it will answer

"Who's calling CQ POTA on 20 m right now?"

"Any DX calling CQ in the last ten minutes, strongest first?"

"Has W9XYZ been heard, and how strong?"

"What is WSJT-X tuned to, and is Tx enabled?"

"Why isn't anything showing up?" — jt_diagnostics

Configure your MCP client

jt-mcp works with any MCP-compatible client. Add the server and restart the client.

Claude Desktop

Add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "jt": {
      "command": "uvx",
      "args": ["jt-mcp"]
    }
  }
}

Claude Code

claude mcp add jt -- uvx jt-mcp

ChatGPT Desktop

Configure via Settings > Apps & Connectors, or in your agent definition, with the same command and args as above.

WSJT-X on another PC

By default jt-mcp listens on 127.0.0.1, this PC alone. For WSJT-X on another PC, give one address of this PC with --bind, and name each PC that may send with --allow:

"args": ["jt-mcp", "--bind", "192.168.1.50", "--allow", "192.168.1.40"]

and set WSJT-X's UDP Server to 192.168.1.50. Listening on every interface at once (0.0.0.0) is refused, --allow is required with a network address, and names are not accepted, only IP addresses. A datagram from anyone else is dropped unread and counted, and jt_diagnostics shows the count and the addresses.

What the allow list does not do. It keeps other machines out. It is not proof of who sent: a UDP sender's address can be forged by anything on the same network. What contains that is that jt-mcp only reads, so a forged datagram can mislead about what WSJT-X is doing and cannot make anything happen.

Options

jt-mcp [--bind ADDR] [--allow ADDR ...] [--udp-port N]
       [--transport stdio|streamable-http] [--port N] [--version] [--help]

Licence

GPL-3.0-or-later. See LICENSE.