io.github.sbrunner-atx/fldigi-mcp
Control fldigi (amateur-radio digital modes) over XML-RPC: modem, frequency, rig, log, transmit.
Open source Open in the app JSON README (API)
About
Control fldigi (amateur-radio digital modes) over XML-RPC: modem, frequency, rig, log, transmit.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- sbrunner-atx
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.4
- Last push
- 2026-07-31T23:44:40Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:22
- Updated
- 2026-08-29 04:01:22
- Origin id
io.github.sbrunner-atx/fldigi-mcp
README
# fldigi-mcp
<!-- mcp-name: io.github.sbrunner-atx/fldigi-mcp -->
An [MCP](https://modelcontextprotocol.io/) server for controlling
[fldigi](https://www.w1hkj.org/), the popular amateur-radio digital-modem
application, from MCP-aware clients such as Claude Desktop.
fldigi ships a built-in XML-RPC control interface. `fldigi-mcp` connects to it
and exposes the whole API as a small set of logically-grouped MCP tools, so an
assistant can read the radio's state and drive the modem, rig, log, and
transmitter through plain language.
> **Status:** beta. Full API coverage, callsign-gated transmit, and an optional
> experimental Band Guidance feature. Tested against fldigi 4.2.x.
## 📻 A field-tested fldigi XML-RPC API reference (free community resource)
Building this server meant mapping fldigi's entire XML-RPC interface and
**verifying every method against a live build** — so we've written it all up and
are sharing it freely, whether or not you ever use this MCP server:
- **[docs/FLDIGI-API.md](docs/FLDIGI-API.md)** — a clean, complete, human-readable
reference organized by namespace, with transport details, types, worked
examples, a transmit-safety section, and field-tested gotchas.
- **[docs/FLDIGI-API.pdf](docs/FLDIGI-API.pdf)** — the same, as a printable PDF.
- **[docs/FLDIGI-API-SPEC.md](docs/FLDIGI-API-SPEC.md)** — a terse,
machine-readable catalog of all **174 methods** (args, return type,
read/write/keying).
Verified live against **fldigi 4.2.11** via `fldigi.list`. It's more complete and
current than the public wiki (it documents methods the wiki omits, e.g. `TxID`,
and flags deprecated ones). **Independent project — not affiliated with the
fldigi / W1HKJ project.** Corrections welcome via
[issues / PRs](https://github.com/sbrunner-atx/fldigi-mcp/issues).
## Highlights
- **Complete control** — every documented XML-RPC method is reachable, grouped
into ~14 tools (one permission each) plus a `fldigi_call` escape hatch for the
long tail and future methods.
- **Safe by default** — the **callsign is the single transmit gate**. With no
callsign configured the station is receive-only; nothing can key the radio.
- **Names match fldigi** — tools and operations mirror fldigi's own API
namespaces and on-screen labels (Op Mode, AFC, SQL, Rev, Lock, RxID/TxID, T/R).
- **No fragile dependencies** — talks to fldigi with Python's standard-library
`xmlrpc.client`. The only third-party runtime deps are the MCP SDK and PyYAML
(for the optional band-plan data).
## Why XML-RPC (and not a third-party library)
fldigi's XML-RPC interface is its official, OS-independent control API. This
project talks to it directly rather than through an unmaintained wrapper,
keeping the moving parts to Python's standard library and fldigi's own API.
## Requirements
To **install the desktop extension** (`.mcpb`) all you need is:
- **fldigi** running (its XML-RPC server is on by default at `127.0.0.1:7362`).
Claude Desktop's `uv` runtime supplies Python and the dependencies, so end users
do **not** install Python or `uv` themselves. (That runtime is currently marked
experimental, so a recent Claude Desktop is recommended.)
For **development from source** you additionally need **Python 3.10+** and
**[uv](https://docs.astral.sh/uv/)** (and **Node.js**, only for the MCP Inspector).
## Install
### Easiest: one-click desktop extension
Download `fldigi-mcp.mcpb` from the latest
[release](https://github.com/sbrunner-atx/fldigi-mcp/releases), then in Claude
Desktop go to **Settings → Extensions → Advanced settings → Install Extension…**
and choose the file.
A short settings form asks for your callsign (everything else has a default).
**No terminal, no Python, no uv to install.**
👉 **New to this? Follow the simple [step-by-step install guide](docs/INSTALL.md).**
Also see the [install & safety model](docs/install-and-safety.md).
### From source (development)
```bash
git clone https://github.com/sbrunner-atx/fldigi-mcp.git
cd fldigi-mcp
uv sync
```
Then add it to Claude Desktop's config
(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"fldigi": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/fldigi-mcp", "run", "fldigi-mcp"],
"env": { "FLDIGI_CALLSIGN": "AE5VG" }
}
}
}
```
Restart Claude Desktop and ask *"What's fldigi's status?"*. Omit the `env` block
to run receive-only.
### Try it with the MCP Inspector
```bash
uv run mcp dev src/fldigi_mcp/server.py
```
## Tools
Each tool is one permission and takes an `operation` argument, so e.g. "change
the mode" is a single permission regardless of which underlying method runs.
| Tool | Controls (fldigi area) |
| --- | --- |
| `status` | quick snapshot: version, mode, frequency, T/R, callsign, band |
| `diagnostics` | host/network info for connectivity troubleshooting (no fldigi connection) |
| `application` | program info + launch/stop the fldigi process (`fldigi.*`) |
| `modem` | Op Mode / modem select, carrier, bandwidth, AFC range, Olivia |
| `frequency` | dial frequency and waterfall sideband |
| `controls` | AFC, SQL, Rev, Lock, RxID, TxID, status fields |
| `transmit` | T/R, Tune, abort, disable/enable Tx, macros, send — **callsign-gated** |
| `rig` | CAT control: mode, frequency, bandwidth, notch, QSY, take/release |
| `log` | Logbook / contest fields; ADIF last/all records |
| `text` | RX/TX text and data streams |
| `spot` | spotting / PSK Reporter |
| `wefax` | WEFAX (weather fax) mode |
| `navtex` | NAVTEX / SitorB mode |
| `band_guidance` | advisory band/watering-hole help (experimental) |
| `fldigi_call` | escape hatch — call any method by name, incl. future ones |
Use `application` → `list_methods` to enumerate every method the running build
supports; anything not surfaced in a group is reachable via `fldigi_call`.
## Configuration
| Variable | Default | Purpose |
| --- | --- | --- |
| `FLDIGI_HOST` | `127.0.0.1` | fldigi XML-RPC host |
| `FLDIGI_PORT` | `7362` | fldigi XML-RPC port |
| `FLDIGI_CALLSIGN` | _(empty)_ | Operator callsign. **The single transmit gate** — set it to enable transmit; blank keeps the station receive-only |
| `FLDIGI_BAND_GUIDANCE` | `off` | Experimental advisory band guidance. `on` to enable |
| `FLDIGI_REGION` | `2` | IARU region for band guidance: `1`, `2`, or `3` |
| `FLDIGI_PATH` | _(auto)_ | Explicit path to the fldigi executable (for `application launch`) |
In the packaged desktop extension these appear as a settings form — most users
only ever fill in the callsign.
### Transmit safety
The **callsign is the single transmit gate**. Keying operations (`transmit`
tx/tune/run_macro/send, and the `wefax`/`navtex` send operations, and any keying
method via `fldigi_call`) refuse unless `FLDIGI_CALLSIGN` is set. With it blank,
the station is receive-only. `rx`, `abort`, and `disable_tx` are always allowed
because they take the station *off* the air. Any non-blank value is accepted
(club, event, vanity, portable, and international calls all work). See
[docs/install-and-safety.md](docs/install-and-safety.md).
### Band Guidance (experimental, off by default)
An optional, advisory feature that suggests a mode's customary "watering hole"
and warns when a frequency falls outside the digital band segment — guidance and
defaults, never hard locks. Region-aware (IARU R1/R2/R3), covering 160 m – 70 cm.
Enable with `FLDIGI_BAND_GUIDANCE=on`. It adds the `band_guidance` tool and
enriches `modem`/`frequency` *set* operations with an advisory `guidance` field.
Because band-plan data is hard to get exactly right, it ships experimental and
disabled by default. Design and data: [docs/band-guidance.md](docs/band-guidance.md).
### Remote / distributed setups
fldigi need not run on the same machine. Point the server at it with
`FLDIGI_HOST`/`FLDIGI_PORT`. The fldigi machine must be launched with
`--xmlrpc-server-address 0.0.0.0` to accept LAN connections, and the link should
be kept on a trusted LAN or tunneled over SSH (the XML-RPC interface is
unauthenticated).
**Sandboxed MCP clients (e.g. Claude Desktop):** the client runs the connector
**sandboxed so it can only reach `127.0.0.1`, not LAN addresses** — so a correct
LAN IP for fldigi will time out even though `telnet` to it works. Use the
standalone [mcp-host-bridge](https://github.com/sbrunner-atx/mcp-host-bridge)
relay on the client computer (it knows `fldigi` = port 7362), then set
`FLDIGI_HOST=127.0.0.1`:
```
pipx install mcp-host-bridge # or download a binary from its releases
mcp-host-bridge install fldigi --to 192.168.1.50
```
Manage it with `mcp-host-bridge status fldigi` / `uninstall fldigi`. The same tool
also bridges N3FJP (for the sibling `n3fjp-mcp`) and any other local service.
## Skills
The [`skills/`](skills/) directory contains agent skills — operating
procedures distilled from live on-air use — bundled with the repo and the
`.mcpb` package:
- **[fldigi-operating](skills/fldigi-operating/SKILL.md)** — TX/RX handoff
done right (`^r` return-to-receive via `transmit → send`, `abort` as the
panic button, never poll the TX buffer), RX-buffer polling discipline
(delta reads, the no-echo rule, restart detection), and a reference CQ
loop. Field-proven during ARRL Field Day 2026.
The **[Operating Skills Field Guide](docs/operating-skills-field-guide.pdf)**
(PDF) documents this skill and its companion `contest-operating` from the
sibling [n3fjp-mcp](https://github.com/sbrunner-atx/n3fjp-mcp) — skills
at a glance, installation, a plain-language "Your first session — Claude for
hams" chapter for operators new to AI, the operating standard, the
special-case playbook, and worked examples transcribed from ARRL Field Day
2026.
To use with Claude Code / Cowork, copy the skill directory into your
`~/.claude/skills/` (or a project's `.claude/skills/`).
## Development
```bash
uv sync
uv run ruff check . # lint
uv run pytest # tests (no running fldigi required)
```
The test suite covers the band-plan logic and the operation maps / type
coercion; it does not require a running fldigi.
## License
[MIT](LICENSE) © 2026 Stefan Brunner (AE5VG)