contest-mcp

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

An MCP server for logging amateur-radio QSOs to N3FJP logging software — 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. contest-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 operates the radio.

Status: experimental (v0.1). 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.

The project is named contest-mcp (not "n3fjp-mcp") to avoid any conflict with the N3FJP name and callsign. It is an independent project and is not affiliated with or endorsed by Affirmatech / N3FJP.

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 contest-mcp.mcpb from the latest release, 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.

From source (development)

git clone https://github.com/sbrunner-atx/contest-mcp.git
cd contest-mcp
uv sync

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

{
  "mcpServers": {
    "contest": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/contest-mcp", "run", "contest-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

uv run mcp dev src/contest_mcp/server.py

Tools

Each tool is one permission and takes an operation argument.

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

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, contest-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: Claude Desktop runs the connector sandboxed 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. The fix ships with the package as a one-command installer — run it on the Claude Desktop computer (macOS/Linux/Windows), then set the host to 127.0.0.1:

pipx install contest-mcp        # or pip install contest-mcp
contest-mcp-forward install --to 192.168.1.50   # auto-starts on login, survives reboots

Manage it with contest-mcp-forward status / uninstall, and change the IP by re-running install --to <new-ip>. Full instructions (macOS, Windows, Linux) are in docs/REMOTE-HOST.md. 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) — 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.

Project docs

• Install guide and Test plan.

Development

uv sync
uv run ruff check .      # lint
uv run pytest            # tests (no running N3FJP required)
python3 smoke_test.py 192.168.1.50 1100   # Phase 0: prove the link to N3FJP

The test suite covers the wire protocol, the operation maps and field catalog, type coercion, and the permission/confirm safety model; none of it requires a running N3FJP.

License

MIT © 2026 Stefan Brunner (AE5VG)