Contest MCP server

n3fjp-mcp

<!-- mcp-name: io.github.sbrunner-atx/n3fjp-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. 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 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 — not to

N3FJP**. MIT licensed. "N3FJP" is the callsign and trademark of its owner.

Highlights

set the call → CALLTAB (dupe check + previous-contact lookup) → set the exchange → ENTER, surfacing the dupe response and the number of records added.

• Automatic logging — the headline log tool runs the real N3FJP flow:

entity checks, band/mode/frequency, direct database operations, and opt-in push notifications, grouped into 9 tools (one permission each), a read-only diagnostics tool, and an n3fjp_call escape hatch for the long tail and future commands.

• Broad coverage — read queries, field read/write, search/list, dupe and

records) sit at Needs Approval, with no extra in-band confirmation.

• 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, and adding, editing or deleting individual

dedicated, off-by-default N3FJPALLOWDB_WIPE switch.

• Whole-database wipes/overwrites are refused outright unless you flip a

(Action ENTER, CALLTAB, the TXTENTRY… boxes, Class/Section, etc.).

• Names match N3FJP — tools and fields mirror N3FJP's own terminology

• No fragile dependencies — the only runtime dependency is the MCP SDK.

Requirements

To install the desktop extension (.mcpb):

"TCP API Enabled"** checked (default API port 1100).

• An N3FJP program running, with **Settings → Application Program Interface →

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 (and Node.js, only for the MCP Inspector).

Install

Easiest: one-click desktop extension

Download n3fjp-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/n3fjp-mcp.git
cd n3fjp-mcp
uv sync

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

Shortened. The full README is on GitHub.