n3fjp-mcp

# n3fjp-mcp

<!-- mcp-name: io.github.sbrunner-atx/n3fjp-mcp -->

An [MCP](https://modelcontextprotocol.io/) server for **logging amateur-radio
QSOs** to [N3FJP logging software](https://www.n3fjp.com/) — Amateur Contact Log
and the 100-plus N3FJP contest loggers — from MCP-aware clients such as Claude
Desktop.

Every program in the N3FJP suite shares one TCP control API. `n3fjp-mcp` speaks
that protocol directly (Python's standard-library `socket`, no third-party
wrapper) and exposes it as a small set of logically-grouped MCP tools, so an
assistant can log contacts, read the log, run dupe checks, and manage band/mode
through plain language.

It is the **logging** half of an "operate → log" workflow; its sibling project
[`fldigi-mcp`](https://github.com/sbrunner-atx/fldigi-mcp) operates the radio.

> **Status:** experimental (v0.3). Verified live against N3FJP's ARRL Field Day
> Contest Log, **API version 2.2**. The protocol is shared across the suite, but
> field sets vary per contest — confirm with the `fields` tool.

> ## ⚠️ Independent project — not affiliated with N3FJP
>
> `n3fjp-mcp` is an independent, community project by **Stefan Brunner (AE5VG)**,
> using the "N3FJP" name with the permission of its owner. It is **not affiliated
> with, endorsed by, or supported by N3FJP Software / Affirmatech**. Please direct
> **all support questions for this app to
> [its issue tracker](https://github.com/sbrunner-atx/n3fjp-mcp/issues) — not to
> N3FJP**. MIT licensed. "N3FJP" is the callsign and trademark of its owner.

## Highlights

- **Automatic logging** — the headline `log` tool runs the real N3FJP flow:
  set the call → `CALLTAB` (dupe check + previous-contact lookup) → set the
  exchange → `ENTER`, surfacing the dupe response and the number of records added.
- **Broad coverage** — read queries, field read/write, search/list, dupe and
  entity checks, band/mode/frequency, direct database operations, and opt-in
  push notifications, grouped into 9 tools (one permission each) plus an
  `n3fjp_call` escape hatch for the long tail and future commands.
- **Safe by design** for a tool that can touch your log database:
  - **Reads** are marked read-only so clients can default them to *Always Allow*.
  - **Writes** (logging, band/mode) default to *Needs Approval*.
  - **Destructive** operations (add-direct, delete a record, raw SQL)
    additionally require `confirm=true`.
  - **Whole-database** wipes/overwrites are refused outright unless you flip a
    dedicated, off-by-default `N3FJP_ALLOW_DB_WIPE` switch.
- **Names match N3FJP** — tools and fields mirror N3FJP's own terminology
  (Action `ENTER`, `CALLTAB`, the `TXTENTRY…` boxes, Class/Section, etc.).
- **No fragile dependencies** — the only runtime dependency is the MCP SDK.

## Requirements

To **install the desktop extension** (`.mcpb`):

- An **N3FJP program** running, with **Settings → Application Program Interface →
  "TCP API Enabled"** checked (default API port `1100`).

Claude Desktop's `uv` runtime supplies Python and the dependencies, so end users
do **not** install Python or `uv` themselves.

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 `n3fjp-mcp.mcpb` from the latest
[release](https://github.com/sbrunner-atx/n3fjp-mcp/releases), then in Claude
Desktop go to **Settings → Extensions → Advanced settings → Install Extension…**
and choose the file. A short settings form asks for the host/port (defaults to
`127.0.0.1:1100`). **No terminal, no Python, no uv to install.**

👉 New to this? Follow the step-by-step [install guide](docs/INSTALL.md).

### From source (development)

```bash
git clone https://github.com/sbrunner-atx/n3fjp-mcp.git
cd n3fjp-mcp
uv sync
```

Then add it to Claude Desktop's config
(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "contest": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/n3fjp-mcp", "run", "n3fjp-mcp"],
      "env": { "N3FJP_HOST": "127.0.0.1", "N3FJP_PORT": "1100" }
    }
  }
}
```

Restart Claude Desktop and ask *"What's the N3FJP status?"*.

### Try it with the MCP Inspector

```bash
uv run mcp dev src/n3fjp_mcp/server.py
```

## Tools

Each tool is one permission and takes an `operation` argument.

| Tool | Default | Controls |
| --- | --- | --- |
| `status` | read | snapshot: program, version, API version, QSO count, band/mode/frequency |
| `query` | read | program, qso_count, next_serial, log/settings/shared paths, qso_rate, band_mode_freq |
| `fields` | read | read one entry box, or list visible / all fields with values |
| `search` | read | list recent, search, dupecheck (no side effects), entity status |
| `log` | **approval** | `log_qso` (set call → CALLTAB → exchange → ENTER), set, set_many, calltab, enter, clear, focus |
| `bandmode` | **approval** | change_freq, set_band, set_mode, ignore_rig_polls |
| `notifications` | **approval** | enable / disable push events, drain buffered events |
| `database` | **approval** | add_direct, delete a record, raw sql, checklog, openlog, sqlclose |
| `n3fjp_call` | **approval** | escape hatch — send any raw command, incl. future ones |

All write tools sit at the **Needs Approval** tier, so you can set them to *Always
Allow* in the client for hands-off automation. The single exception is a
whole-database wipe (see below), which is hard-blocked regardless.

The headline is `log` → `log_qso`:

```
log_qso  call="W1AW"  contest="field_day"  exchange={"class":"2A","section":"CT"}
```

This sets the call, fires `CALLTAB` (dupe check), fills the exchange, sends
`ENTER`, and reports records added plus any dupe detail.

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `N3FJP_HOST` | `127.0.0.1` | N3FJP API host |
| `N3FJP_PORT` | `1100` | N3FJP API port (the suite's default) |
| `N3FJP_TIMEOUT` | `6` | Socket/response timeout, seconds |
| `N3FJP_ALLOW_DB_WIPE` | `off` | **Danger.** Allow whole-database delete/overwrite (raw SQL `DROP`/`TRUNCATE`/unscoped `DELETE`/`UPDATE`). Leave **off** unless you really mean it |

In the packaged desktop extension these appear as a settings form.

### Safety model

Logging doesn't key a transmitter, so there is no transmit gate. The protection
here is about your **log database**:

- **Read** operations (`status`, `query`, `fields`, `search`) are marked
  read-only — clients can default them to *Always Allow*.
- **Write** operations — logging (`log`), band/mode (`bandmode`),
  notifications, and **adding, editing, or deleting individual records**
  (`database`), plus the `n3fjp_call` escape hatch — all sit at the *Needs
  Approval* tier. There is no extra in-band confirmation, so you can set them to
  *Always Allow* in the client and let automation run hands-off.
- **Whole-database** operations — raw SQL that could delete or overwrite the
  entire log (`DROP`, `TRUNCATE`, a `DELETE`/`UPDATE` with no `WHERE`) — are the
  one exception: **refused** unless `N3FJP_ALLOW_DB_WIPE` is on. This switch is
  separate from, and stricter than, the client's approval prompts, and carries a
  stern warning in the settings form. **Back up your log before ever enabling
  it.**

Wherever possible, `n3fjp-mcp` leans on N3FJP's own validation (it dupe-checks
and reports oddities) and surfaces those responses rather than re-implementing
them.

### Remote / contest-station setups (N3FJP on another computer)

If N3FJP runs on the **same** computer as Claude Desktop (the common case), leave
`N3FJP_HOST` at `127.0.0.1` and you're done.

If N3FJP runs on a **different** computer, there's a catch: a **sandboxed** MCP
client (notably Claude Desktop) runs the connector so it can only reach
`127.0.0.1`, not LAN addresses — so putting N3FJP's LAN IP in the settings will
time out even though `telnet` to that IP works. Fix it with the standalone
[mcp-host-bridge](https://github.com/sbrunner-atx/mcp-host-bridge) tool on the
client computer, then set the host to `127.0.0.1`:

```
pipx install mcp-host-bridge            # or download a binary from its releases
mcp-host-bridge install n3fjp --to 192.168.1.50   # knows n3fjp = port 1100; auto-starts
```

Manage it with `mcp-host-bridge status n3fjp` / `uninstall n3fjp`. Full details
are in [docs/REMOTE-HOST.md](docs/REMOTE-HOST.md) and the
[mcp-host-bridge README](https://github.com/sbrunner-atx/mcp-host-bridge#readme).
The `diagnostics` tool helps confirm whether you need it. Keep the link on a
trusted LAN — the API is unauthenticated.

## Documentation

### 📻 A field-tested N3FJP API reference (free community resource)

Building this server meant reverse-engineering and **live-verifying** the N3FJP
TCP API, including several places where today's API (v2.2) differs from the
public 0.9 documentation. We've written that up as a complete, human-readable
guide and are sharing it freely to give back to the community:

- **[The N3FJP TCP API — A Field-Tested Reference](docs/N3FJP-API.md)**
  ([PDF](docs/N3FJP-API.pdf)) — transport, every command grouped by area,
  verified response examples, contest exchange fields, and a hard-won
  **gotchas** section (the API vs. networking ports, `CMD_NOT_FOUND`, commands
  removed since 0.9, the `CALLTABEVENT` lookup, and why `ENTER` can report 0 yet
  still log in networked mode).
- **[Machine-readable spec](docs/N3FJP-API-SPEC.md)** — the same information in a
  terse, structured command catalog suitable for code generation.

Corrections and additions are welcome — please
[open an issue or PR](https://github.com/sbrunner-atx/n3fjp-mcp/issues).

### Project docs

- [Install guide](docs/INSTALL.md) and [Test plan](docs/TEST-PLAN.md).
- [Field Day 2026 lessons learned](docs/LESSONS-FIELD-DAY-2026.md) — the
  full after-action report from running an autonomous BPSK31 Field Day
  station (class 2A, callsigns anonym