使用说明
WSJT-X MCP Server
Control your Amateur Radio station with AI.
The WSJT-X MCP Server bridges the gap between modern AI agents (like Claude, ChatGPT, or Gemini) and the popular WSJT-X software. It enables your AI assistant to monitor radio traffic, analyze signals, and autonomously conduct QSOs on modes like FT8 and FT4.
Features
- AI-Driven Control: Exposes WSJT-X functionality via the Model Context Protocol (MCP).
- Multi-Instance Support: Control multiple radios/bands simultaneously from a single AI session.
- Autonomous QSOs: "Fire-and-forget" QSO automation—tell the AI to "work that station," and the server handles the complete exchange sequence.
- Windows Native: Designed primarily for Windows, with optional support for Raspberry Pi.
- Dual Operation Modes:
- FlexRadio Mode: Auto-launch WSJT-X instances for each slice with built-in CAT server (no external SmartCAT needed).
- Standard Mode: Direct control for standard rigs (default: IC-7300).
- Web Dashboard: Real-time monitoring and manual control interface on port 3000.
- Live Monitoring: Stream decoded messages and signal reports directly to the AI context.
Architecture
The MCP Server runs locally on the same machine as your WSJT-X instances (PC or Raspberry Pi). It acts as a middleware, translating MCP requests from the AI Agent into UDP commands for WSJT-X.
Standard Mode
AI Agent <--MCP/stdio--> MCP Server <--UDP 2237--> WSJT-X <--CAT--> Radio (IC-7300)
FlexRadio Mode
AI Agent <--MCP/stdio--> MCP Server
|
+---------------+---------------+
| | |
FlexClient FlexRadio HrdCatServer
(VITA 49) Manager (HRD Protocol)
| | |
+-------+-------+-------+-------+
| |
SmartSDR WSJT-X
| Instances
FlexRadio (per slice)
FlexRadio Features:
- Auto-discovery of FlexRadio on the network
- Auto-launch WSJT-X instance for each slice
- Built-in HRD CAT server (ports 7809-7812)
- Bidirectional control: WSJT-X frequency/mode/PTT changes sync to FlexRadio
- Auto-configuration of WSJT-X INI files (audio, rig, wide graph)
Capabilities
| Category | Functionality |
|---|---|
| Management | Start/Stop instances, List active radios |
| Monitoring | Live decodes, Frequency/Mode status, Signal reports |
| Control | Set Frequency, Change Mode, PTT control |
| Automation | Call CQ, Reply to Station, Execute Full QSO |
| Visualization | Web Dashboard (port 3000), Action Logs |
Installation
Prerequisites
- Node.js (v18+)
- WSJT-X installed (default:
C:\WSJT\wsjtx\bin\wsjtx.exe) - For FlexRadio mode: SmartSDR running
Quick Start
# Clone the repository
git clone https://github.com/SensorsIot/wsjt-x-MCP.git
cd wsjt-x-MCP
# Install dependencies
npm install
# Build TypeScript
npx tsc
# Run the server
npm start
Web Dashboard
cd frontend
npm install
npm run dev # Development with hot reload
# or
npm run build # Production build
Access the dashboard at: http://localhost:3000
Configuration
Configuration is stored in config.json:
Standard Mode (default)
{
"mode": "STANDARD",
"wsjtx": {
"path": "C:\\WSJT\\wsjtx\\bin\\wsjtx.exe"
},
"station": {
"callsign": "YOUR_CALL",
"grid": "YOUR_GRID"
},
"standard": {
"rigName": "IC-7300"
}
}
FlexRadio Mode
{
"mode": "FLEX",
"wsjtx": {
"path": "C:\\WSJT\\wsjtx\\bin\\wsjtx.exe"
},
"station": {
"callsign": "YOUR_CALL",
"grid": "YOUR_GRID"
},
"flex": {
"host": "auto",
"catBasePort": 7831
}
}
Environment Variables
WSJTX_MODE: Set toFLEXfor FlexRadio mode (default:STANDARD)FLEX_HOST: FlexRadio IP address (default: auto-discovery)RIG_NAME: Rig name for Standard mode (default:IC-7300)
MCP Tools
The server exposes these tools to AI agents:
| Tool | Description |
|---|---|
start_instance |
Launch a new WSJT-X instance |
stop_instance |
Stop a running instance |
execute_qso |
Autonomously complete a QSO with a target station |
Project Structure
wsjt-x-MCP/
├── src/
│ ├── index.ts # Entry point
│ ├── SettingsManager.ts # Configuration management
│ │
│ ├── wsjtx/ # WSJT-X management
│ │ ├── WsjtxManager.ts # Main orchestrator
│ │ ├── ProcessManager.ts # WSJT-X process lifecycle
│ │ ├── FlexRadioManager.ts # FlexRadio slice management
│ │ ├── UdpListener.ts # UDP message receiver
│ │ ├── UdpSender.ts # UDP message sender
│ │ ├── QsoStateMachine.ts # Autonomous QSO handler
│ │ ├── WindowManager.ts # WSJT-X window positioning
│ │ └── WsjtxConfig.ts # INI file auto-configuration
│ │
│ ├── state/ # MCP state management
│ │ ├── StateManager.ts # Aggregate MCP state
│ │ ├── ChannelUdpManager.ts # Per-channel UDP
│ │ └── types.ts
│ │
│ ├── logbook/ # Logbook operations
│ │ └── LogbookManager.ts # ADIF, WorkedIndex, HRD server
│ │
│ ├── dashboard/ # Web dashboard state
│ │ └── DashboardManager.ts # Station tracking
│ │
│ ├── cat/ # CAT control
│ │ └── HrdCatServer.ts # HRD protocol server
│ │
│ ├── flex/ # FlexRadio backend
│ │ ├── FlexClient.ts # FlexRadio connection
│ │ ├── Vita49Client.ts # VITA 49 protocol
│ │ └── FlexDiscovery.ts # Auto-discovery
│ │
│ ├── mcp/ # MCP protocol
│ │ └── McpServer.ts # MCP stdio transport
│ │
│ └── web/ # Web interface
│ └── server.ts # Express + WebSocket
│
├── frontend/ # React web dashboard
├── dist/ # Compiled JavaScript
└── config.json # Runtime configuration
Documentation
- WSJT-X-MCP-FSD.md - Full Functional Specification Document
- CLAUDE.md - Development guide for Claude Code
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License - see the LICENSE file for details.
