n1mm-mcp¶

MCP server for N1MM Logger+: live contest state — station, QSOs, bandmap, score and rate, multipliers, and contest clock — through any MCP-compatible AI assistant.

Data from N1MM Logger+'s UDP broadcasts on your local network. Part of the qso-graph project. No authentication required.

Install¶

uvx n1mm-mcp            # run it; nothing to install

Tools¶

Tool	Description	Key Parameters
`n1mm_current_state`	Station snapshot: connection, contest, operator, radios	station_name
`n1mm_lookup`	The callsign being entered (pre-log) plus current band and mode	station_name
`n1mm_contacts`	QSO log: recent contacts, edits and deletes	count, since, band, mode, call_pattern
`n1mm_bandmap`	Live spots, multiplier targets, band activity	band, mode, callsign, mults_only
`n1mm_performance`	Score, rate, bands, run/S&P, hourly timeline	band, mode
`n1mm_multipliers`	Multiplier grid, needs, value analysis	band
`n1mm_clock`	Contest timing, off-time, pacing	duration_hours, target_score, target_qsos, min_gap_minutes
`n1mm_diagnostics`	Server health, parse errors, memory	station_name
`n1mm_so2r`	Two radios: each radio now, transmit/receive focus, same-band warning, transmit time and minutes per band, focus swaps, QSOs per radio and while the other radio runs	station_name
`n1mm_network`	Every networked station: operator, radios, rate, idle time, band, shared score per contest call, stations sharing a band and mode, QSOs per operator	—
`n1mm_pileup`	DXpedition pileup: rate, unique calls, dupes, continents and countries calling, split, dead air	window_minutes
`get_version_info`	Service version + upstream spec version (fleet identity attestation)	—

Every tool except n1mm_network (which covers all stations) takes an optional station_name for multi-station setups.

Everything comes from N1MM's UDP broadcasts; n1mm-mcp never talks to a radio. N1MM reports transmitting only when it keys the radio itself (macros, its CW keyer), so a paddle or microphone PTT doesn't count as transmit time in n1mm_so2r.

What is N1MM Logger+?¶

N1MM Logger+ is a Windows contest logger. It can broadcast its state over UDP: contacts, spots, radio info and score. n1mm-mcp listens to those broadcasts and keeps the contest state in memory, so an assistant can answer questions about it. N1MM doesn't know it's there.

N1MM Logger+ (Windows)
    │ UDP broadcast (port 12060, XML)
    ▼
n1mm-mcp (Python: the same PC, or any OS on the LAN)
    ├── UDP listener (background)
    ├── State engine (in memory, per StationName)
    │   MCP protocol (stdio)
    ▼
AI assistant

Quick Start¶

Turn on N1MM's broadcasts¶

In N1MM: Config → Configure Ports → Broadcast Data, and enable all message types.
Set the destination to 127.0.0.1:12060, N1MM's address for "this PC". n1mm-mcp listens there by default, and nothing outside the PC can reach it.

N1MM on another PC¶

Run n1mm-mcp with --bind 0.0.0.0 (every network interface) or --bind <this PC's LAN address>, and point N1MM at it: this PC's address (192.168.1.20:12060), or your subnet's broadcast address (192.168.1.255:12060) to reach every PC on it. N1MM accepts several destinations separated by spaces. Don't use 255.255.255.255: N1MM's own documentation warns that it risks broadcasting to the internet (N1MM: External UDP Broadcasts).

Listening on the network means any device on it can send n1mm-mcp packets, so only do it on a network you trust.

Configure your MCP client¶

n1mm-mcp works with any MCP-compatible client. Add the server config and restart. The tools appear automatically.

Claude Desktop¶

Add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "n1mm": {
      "command": "uvx",
      "args": ["n1mm-mcp"]
    }
  }
}

Claude Code¶

Add to .claude/settings.json:

{
  "mcpServers": {
    "n1mm": {
      "command": "uvx",
      "args": ["n1mm-mcp"]
    }
  }
}

ChatGPT Desktop¶

{
  "mcpServers": {
    "n1mm": {
      "command": "uvx",
      "args": ["n1mm-mcp"]
    }
  }
}

Cursor¶

Add to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "n1mm": {
      "command": "uvx",
      "args": ["n1mm-mcp"]
    }
  }
}

VS Code / GitHub Copilot¶

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "n1mm": {
      "command": "uvx",
      "args": ["n1mm-mcp"]
    }
  }
}

Gemini CLI¶

Add to ~/.gemini/settings.json (global) or .gemini/settings.json (project):

{
  "mcpServers": {
    "n1mm": {
      "command": "uvx",
      "args": ["n1mm-mcp"]
    }
  }
}

Ask questions¶

"What's my rate over the last hour?"

"Which multipliers do I still need on 20m?"

"Is the station on the bandmap a new multiplier?"

"How much off-time have I used, and am I on pace for my target?"

"Show me the last 10 QSOs."

CLI Options¶

Option	Default	Description
`--port`	`12060`	UDP listen port
`--bind`	`127.0.0.1`	Address to listen on; `0.0.0.0` for N1MM on another PC
`--transport`	`stdio`	MCP transport (`stdio` or `streamable-http`)
`--heartbeat-timeout`	`60`	Seconds before the connection goes stale
`--stale-timeout`	`900`	Seconds before the connection goes disconnected
`--max-spots`	`2000`	Maximum spots in the bandmap buffer
`--spot-ttl`	`30`	Spot time-to-live in minutes

Testing Without N1MM¶

N1MM_MCP_MOCK=1 n1mm-mcp

MCP Inspector¶

n1mm-mcp --transport streamable-http

Then open the MCP Inspector at http://localhost:8008.

Development¶

git clone https://github.com/qso-graph/n1mm-mcp.git
cd n1mm-mcp
uv sync --group dev
uv run pytest

License¶

GPL-3.0-or-later

Tool Reference¶

Generated from the released server's own tool definitions.

get_version_info¶

Get n1mm-mcp service version and upstream UDP contract version.

Returns the running PyPI version of n1mm-mcp and the N1MM Logger+ UDP broadcast contract revision in use. Use this to confirm fleet alignment across MCP deployments — agents can compare service_version and spec_version across servers to detect drift without going outside the MCP protocol.

Note: n1mm_diagnostics remains the canonical health probe (heartbeat, parse errors, memory). get_version_info is a lighter-weight identity attestation that succeeds even when N1MM isn't broadcasting.

No parameters.

n1mm_bandmap¶

Live bandmap — spots, mult targets, and activity summary.

Returns active spots (with TTL eviction), unworked multipliers, and per-band spot activity counts in one snapshot.

Parameter	Type	Required	Default	Description
`band`	string	No	`null`	Filter by band (e.g., "20m").
`mode`	string	No	`null`	Filter by mode.
`callsign`	string	No	`null`	Search by callsign prefix.
`mults_only`	boolean	No	`false`	If true, only return spots flagged as multipliers.
`station_name`	string	No	`null`	Station to query.

n1mm_clock¶

Contest clock — timing, off-time, and pacing in one view.

Parameter	Type	Required	Default	Description
`duration_hours`	number	No	`null`	Contest length (e.g., 48 for CQ WW, 24 for ARRL DX).
`target_score`	integer	No	`null`	Target score for pacing.
`target_qsos`	integer	No	`null`	Target QSO count for pacing.
`min_gap_minutes`	integer	No	`30`	Minimum gap to count as off-time (default 30).
`station_name`	string	No	`null`	Station to query.

n1mm_contacts¶

QSO log — recent contacts, edits, and deletes.

Returns the last QSO, filtered recent QSOs, recent edits, and recent deletes in one coherent snapshot.

Parameter	Type	Required	Default	Description
`count`	integer	No	`10`	Number of recent QSOs to return (default 10, max 100).
`since`	string	No	`null`	ISO timestamp — return only QSOs after this time.
`band`	string	No	`null`	Filter by band (e.g., "20m").
`mode`	string	No	`null`	Filter by mode (e.g., "CW").
`call_pattern`	string	No	`null`	Filter by callsign prefix.
`station_name`	string	No	`null`	Station to query (auto-detected if only one).

n1mm_current_state¶

Complete station snapshot — connection, contest, operator, radios.

Returns connection status, contest info, operator callsign, and full radio state for Radio 1 (and Radio 2 if SO2R). This is the first tool any AI session should call.

Parameter	Type	Required	Default	Description
`station_name`	string	No	`null`

n1mm_diagnostics¶

Server health and diagnostics — connection, parse errors, memory.

Essential for production debugging. First tool to call when something goes wrong during a contest.

Parameter	Type	Required	Default	Description
`station_name`	string	No	`null`

n1mm_lookup¶

Pre-log callsign lookup — THE Contest-Copilot trigger.

Fires when operator types a callsign and presses spacebar in N1MM. Returns the lookup data plus current band/mode from RadioInfo. Check lookup_age_ms — if >30000, the advice window has closed.

Parameter	Type	Required	Default	Description
`station_name`	string	No	`null`

n1mm_multipliers¶

Multiplier status — worked mults, mult map, and available needs.

Returns total mults worked, per-band mult grid, unworked mults currently spotted, and mult value analysis.

Parameter	Type	Required	Default	Description
`band`	string	No	`null`	Filter to specific band.
`station_name`	string	No	`null`	Station to query.

n1mm_network¶

Every networked N1MM station at once (multi-op).

Per station: operator, radios (band, mode, running, transmitting), QSOs, rate over 10 and 60 minutes, mults in the last hour, minutes since the last QSO, the band of its recent QSOs with minutes on it and band changes in the last hour, and when it was last heard. Also: which stations are on each band, stations sharing a band and mode, each station's contest score (shared per contest call), and QSOs per operator this hour against the hour before.

No parameters.

n1mm_performance¶

Complete performance snapshot — score, rate, bands, run/S&P, timeline.

Returns score, rolling rates (10m/30m/60m), rate derivative for band exhaustion detection, per-band breakdown, per-mode breakdown, hourly summary, and run vs S&P stats in one coherent view.

Parameter	Type	Required	Default	Description
`band`	string	No	`null`	Filter rate/breakdown to specific band.
`mode`	string	No	`null`	Filter to specific mode.
`station_name`	string	No	`null`	Station to query.

n1mm_pileup¶

DXpedition pileup view: rate, who's calling, dupes, split, dead air.

Over the last window_minutes (default 60, 5 to 1440): QSOs, unique calls, dupes (a call already worked on that band and mode), run share, rate over 5, 15 and 60 minutes and the best 10 minutes in the window, QSOs and share by continent, the top 10 country prefixes, QSOs by band and mode, gaps of 2 minutes or more between QSOs, and the active radio's split (RX, TX, kHz up).

Parameter	Type	Required	Default	Description
`window_minutes`	integer	No	`60`	How far back to look, in minutes.
`station_name`	string	No	`null`	Station to query.

n1mm_so2r¶

Two-radio (SO2R) view: both radios now, and how they've been used.

Returns each radio's band, frequency, mode and run/transmit state, N1MM's transmit focus and receive focus, whether both radios are on the same band, each radio's share of N1MM-keyed transmit time (a paddle or PTT isn't reported by N1MM) and minutes per band, transmit- and receive-focus swaps, QSOs per radio, and QSOs made on one radio while the other was running. Timing covers the RadioInfo packets seen since the MCP server started (or the contest changed). Read from N1MM's broadcasts; no rig is read.

Parameter	Type	Required	Default	Description
`station_name`	string	No	`null`