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