fldigi-mcp

# 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 fl