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

• 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 (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/claude_desktop_config.json on macOS):