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

Related MCP server: qrz-mcp

Tools

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:

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

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

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