N1mm Mcp

io.github.qso-graphPublished by GitHub account qso-graphv0.5.0Updated Nov 14, 2026

N1MM Logger+ MCP server. Live contest state: QSOs, bandmap, score, rate, multipliers.

VerifiedSTDIODesktop onlyCommunication & CollaborationData & Analytics

Overview

AI-generated overview

Read-only MCP server that turns N1MM Logger+ contest UDP broadcasts into live station, QSO, bandmap, score, rate and multiplier queries for an AI assistant.

What you can do
  • Inspect station state: connection, contest, operator, radios, and the callsign being entered
  • Query the QSO log by count, time, band, mode or call pattern, including edits and deletes
  • Read the bandmap: live spots, multiplier targets and band activity
  • Analyze performance: score, rate, run/S&P, hourly timeline, multiplier needs and contest clock pacing
  • Review two-radio and network setups: per-radio focus and transmit time, and every networked station's rate and shared score
  • Check server health, parse errors and memory, plus version info
When to use it
Useful during or after a ham radio contest when you run N1MM Logger+ and want an assistant to answer questions about your rate, needed multipliers, off-time pacing, recent contacts or multi-station activity.
Requirements
Runs locally as a Python package via uvx (or pip); no authentication or API keys. N1MM Logger+ must broadcast its state over UDP, by default to 127.0.0.1:12060, with broadcast message types enabled. For N1MM on another PC, a network bind address plus an allow-list of sender addresses is required. A mock mode exists for testing without N1MM.
Before you install
Read-only: it has no tool that writes to N1MM, the log or anything else. UDP sender addresses can be forged, so the allow-list keeps other machines out but does not prove who sent a datagram; a forged packet could mislead about contest state. Treat reported state as unverified and run on a trusted network. Binding to 0.0.0.0 is refused.

Installation

In SourceWeft

  1. Open N1mm Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

n1mm-mcp

[PyPI] [MCP Registry]

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

bash
uvx n1mm-mcp            # run it; nothing to install

Tools

ToolDescriptionKey Parameters
n1mm_current_stateStation snapshot: connection, contest, operator, radiosstation_name
n1mm_lookupThe callsign being entered (pre-log) plus current band and modestation_name
n1mm_contactsQSO log: recent contacts, edits and deletescount, since, band, mode, call_pattern
n1mm_bandmapLive spots, multiplier targets, band activityband, mode, callsign, mults_only
n1mm_performanceScore, rate, bands, run/S&P, hourly timelineband, mode
n1mm_multipliersMultiplier grid, needs, value analysisband
n1mm_clockContest timing, off-time, pacingduration_hours, target_score, target_qsos, min_gap_minutes
n1mm_diagnosticsServer health, parse errors, memorystation_name
n1mm_so2rTwo 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 runsstation_name
n1mm_networkEvery networked station: operator, radios, rate, idle time, band, shared score per contest call, stations sharing a band and mode, QSOs per operator—
n1mm_pileupDXpedition pileup: rate, unique calls, dupes, continents and countries calling, split, dead airwindow_minutes
get_version_infoService 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

  1. In N1MM: Config → Configure Ports → Broadcast Data, and enable all message types.
  2. 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

Give one address of this PC and name who may send:

bash
n1mm-mcp --bind 192.168.1.20 --allow 192.168.1.40

Then point N1MM at this PC's address (192.168.1.20:12060), or at 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).

--allow is required whenever --bind is a network address, and is repeatable for more than one PC. A datagram from any other address is dropped without being read, and counted — n1mm_diagnostics shows the count and the addresses, so traffic you did not expect is visible rather than silent.

--bind 0.0.0.0 is refused. It listened on every interface at once, including whatever Wi-Fi a laptop happened to be joined to, and it cannot be narrowed afterwards. Name the interface you mean.

What the allow-list does and does not do

A UDP sender's address can be forged by anything on the same network, so the list keeps other machines out; it is not proof of who sent a datagram. What limits the damage is that n1mm-mcp only reads: it has no tool that writes to N1MM, your log, or anything else. A forged packet can therefore mislead you about contest state—a wrong frequency, a spot that was never spotted—but it cannot act, and nothing it contains is written anywhere. Treat the state as reported, not as verified, and run 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):

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

Add to .claude/settings.json:

json
{  "mcpServers": {    "n1mm": {      "command": "uvx",      "args": ["n1mm-mcp"]    }  }}
ChatGPT Desktop
json
{  "mcpServers": {    "n1mm": {      "command": "uvx",      "args": ["n1mm-mcp"]    }  }}
Cursor

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

json
{  "mcpServers": {    "n1mm": {      "command": "uvx",      "args": ["n1mm-mcp"]    }  }}
VS Code / GitHub Copilot

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

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

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

json
{  "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

OptionDefaultDescription
--port12060UDP listen port
--bind127.0.0.1Address to listen on. One address of this PC; 0.0.0.0 is refused
--allowthis PCAn address that may send to us; repeatable. Required with a network --bind
--transportstdioMCP transport (stdio or streamable-http)
--heartbeat-timeout60Seconds before the connection goes stale
--stale-timeout900Seconds before the connection goes disconnected
--max-spots2000Maximum spots in the bandmap buffer
--spot-ttl30Spot time-to-live in minutes

Testing Without N1MM

bash
N1MM_MCP_MOCK=1 n1mm-mcp

MCP Inspector

bash
n1mm-mcp --transport streamable-http

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

Development

bash
git clone https://github.com/qso-graph/n1mm-mcp.gitcd n1mm-mcpuv sync --group devuv run pytest

License

GPL-3.0-or-later

Source: README.md at commit 246ef12

Tools

12

get_version_info

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.

Takes no parameters.

n1mm_current_state

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.

Parametersstation_name

n1mm_lookup

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.

Parametersstation_name

n1mm_contacts

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.

Parametersbandmodecountsincecall_patternstation_name

n1mm_bandmap

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.

Parametersbandmodecallsignmults_onlystation_name

n1mm_performance

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.

Parametersbandmodestation_name

n1mm_multipliers

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.

Parametersbandstation_name

n1mm_clock

N1Mm Clock

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

Parameterstarget_qsosstation_nametarget_scoreduration_hoursmin_gap_minutes

n1mm_so2r

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.

Parametersstation_name

n1mm_network

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.

Takes no parameters.

n1mm_pileup

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).

Parametersstation_namewindow_minutes

n1mm_diagnostics

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.

Parametersstation_name

Version history

10
  1. v0.5.0LatestNov 14, 2026
  2. v0.4.0Oct 26, 2026
  3. v0.3.2Oct 26, 2026
  4. v0.3.1Oct 26, 2026
  5. v0.3.0Oct 19, 2026
  6. v0.2.1Oct 11, 2026
  7. v0.2.0Oct 7, 2026
  8. v0.1.8Oct 6, 2026
  9. v0.1.7Oct 4, 2026
  10. v0.1.6Sep 29, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts