radio-free-ai

A local MCP server for ham radio, built around MCP Apps so tools can render interactive UI in the host.

Right now it's a map: grayline, Maidenhead grids, and points the model can add and remove while the map is on screen.

Installing in Claude

This repo is a Claude plugin marketplace. The plugin includes the Radio Free AI server and skills for using the map on the air. Claude starts the server on your computer when it needs it.

You need Node.js 20 or later installed and on your PATH. An installer that removes this requirement is coming.

1. Add the marketplace guyroyse/radio-free-ai in Claude.

2. Install the radio-free-ai plugin.

3. Ask Claude to show you the radio map.

In Claude Code, steps 1 and 2 are one command:

/plugin install radio-free-ai --marketplace guyroyse/radio-free-ai

The plugin lives in plugins/radio-free-ai:

• .claude-plugin/plugin.json starts the bundled server over stdio

• server/ holds the built server and map view, committed because plugins install straight from git

• skills/radio-map teaches Claude how to drive the map tools

• skills/maidenhead-and-grayline covers grid locators, grid chasing, and grayline propagation

Related MCP server: Map Canvas MCP

Running

npm install
npm run build        # builds the view and the stdio server into plugins/radio-free-ai/server, then typechecks
npm start            # runs the bundled server on stdio
npm run start:http   # runs the server over HTTP on http://127.0.0.1:3737/mcp

Run npm run build and commit plugins/radio-free-ai/server whenever the source changes, or the plugin ships stale code.

The HTTP server is for sharing one server between several clients or machines, and is where the stdio server will eventually relay to. RADIO_FREE_AI_HOST and RADIO_FREE_AI_PORT override its bind address. It binds to loopback by default; the Host and Origin checks in src/server/http.ts will need loosening before it can serve the LAN.

Opening plugins/radio-free-ai/server/map.html directly in a browser shows the view with demo data.

Tools

Locations are either a Maidenhead grid (FN31, FN31pr) or { lat, lon }.

Privacy

The Radio Free AI server runs on your own computer and talks only to the Claude app that started it. The map is drawn from data bundled with the app, so showing it sends nothing over the network. Your callsign, grid, and anything you put on the map stay in the server's memory on your machine and are gone when it stops. Claude sees what its tools send back, as with any MCP server.

Layout

• src/server — the stdio and HTTP entry points, tool registration, and the MapStore that holds map state

• src/view — the MCP App, bundled to one self-contained HTML file because hosts sandbox it with no external origins

• src/shared — Maidenhead and great-circle math used by both