Skip to main content
Glama
qso-graph

netlogger-mcp

by qso-graph

netlogger-mcp

MCP server and Python library for amateur-radio net logging: which nets are on the air, who has checked in, who's up now, and what past nets logged.

  • Read-only. It never writes to a net.

  • One contract, more than one source. Every answer uses the same net and check-in records (schema/contract.schema.json), whatever logging system is behind them. The first source is NetLogger's public XML Data Service (API 1.3). The next is the OM-Logger being built for OMISS.

  • A good neighbour. NetLogger is a donation-funded service. This server never exceeds NetLogger's published call limits, caches every answer, and backs off when told to.

  • Private details stay out. Street addresses, ZIP codes and IP addresses in NetLogger's data have no place in the contract, so they never reach an AI, a program or a user.

Status: in development (0.1.0, not yet on PyPI).

Tools

Tool

NetLogger call

Returns

netlogger_active_nets

GetActiveNets

nets on the air: server, name, frequency, band, mode, net control, logger, opened, monitoring count

netlogger_checkins

GetCheckins

a live net's check-ins, the count, and the pointer (the station up now)

netlogger_past_nets

GetPastNets

closed nets over the last N days, with the net IDs past check-ins need

netlogger_past_checkins

GetPastNetCheckins

a closed net's check-ins

get_version_info

none

server version, NetLogger API version, contract version

These are all the calls NetLogger's API 1.3 documents. GetPointer is deprecated; the pointer comes with GetCheckins, so it's never called.

Related MCP server: lotw-mcp

Call limits

Call

NetLogger's limit

Answers reused for

GetActiveNets

1 a minute

60 s; the name filter is applied locally, so any number of filters cost one call

GetCheckins

3 a minute

20 s per net

GetPastNets

1 a minute

60 s per query

GetPastNetCheckins

10 a minute

an hour (a closed net's list doesn't change)

A limit is checked before a request is sent, never after. Over the limit, the answer comes from cache with its age (age_seconds, stale), or the result says when to try again. A 429 Too Many Requests on any call stops all calls to NetLogger for at least a minute, longer if NetLogger's Retry-After asks. NetLogger's anti-flooding is aimed at the client, and every call reaches the same server. Past nets older than 7 days need a name filter (NetLogger's rule).

The limits are per process. Every tool call in one server shares them.

Install

pip install netlogger-mcp   # once released

Claude Code / Claude Desktop:

"netlogger": { "command": "netlogger-mcp" }

No API key or password is needed. Your callsign is.

Your callsign

Every request tells NetLogger which station is asking, in the User-Agent:

netlogger-mcp/0.1.0 (KI7MT; +https://github.com/qso-graph/netlogger-mcp)

That way, NetLogger can tell users apart. Without it, every install would look like one client, and one misbehaving install could get everyone blocked. There is no anonymous mode.

  • Nothing to configure. On first use, the server says it needs your callsign, the AI asks you, and it's saved (netlogger_set_callsign). You're asked once.

  • Saved in a small settings file: ~/.config/netlogger-mcp/settings.json on Linux, ~/Library/Application Support/netlogger-mcp/ on macOS, %APPDATA%\netlogger-mcp\ on Windows. A callsign is public, not a password.

  • Or set it with NETLOGGER_MCP_CALLSIGN=KI7MT, which overrides the file.

  • Changing the callsign never resets the call limits.

For testing without the network, set NETLOGGER_MCP_MOCK=1 to answer from bundled synthetic samples.

As a library

Programs that don't need an AI use the same code directly, with the same limits, cache and contract. A library can't ask anyone anything, so it requires the callsign: the program passes in the signed-in user's callsign, or the club's for a shared server.

from netlogger_mcp.netlogger import NetLoggerSource

# callsign: required (no valid callsign: NetLoggerError, nothing sent).
# program_id / program_version: your app, as in ADIF's PROGRAMID and PROGRAMVERSION (optional).
nl = NetLoggerSource(callsign="KI7MT", program_id="OM-Logger", program_version="0.3")
# User-Agent: OM-Logger/0.3 netlogger-mcp/0.1.0 (KI7MT; +https://github.com/qso-graph/netlogger-mcp)
for net in nl.active_nets(name_like="OMISS")["nets"]:
    live = nl.checkins(net["server"], net["name"])
    print(net["name"], "up now:", live["pointer"])

Programs in other languages can run the server and call its tools over MCP (JSON-RPC on stdio or HTTP).

Terms and privacy

NetLogger's terms allow API use "in direct support of Radio Communications". This server is for that. It sends a User-Agent naming this project and the station using it. Parsing follows the spec: no assumptions about node order or count, unknown elements ignored, <Warning> messages logged for the developer. XML is parsed with defusedxml.

Development

pip install -e ".[test]"
pytest

Part of qso-graph. Licensed GPL-3.0-or-later.

Available Tools

6 tools
get_version_infoGet Version InfoA

Get netlogger-mcp's version, the NetLogger API version it is built for, and the version of the records it returns.

Returns: service_name, service_version (PyPI), spec_version (NetLogger API), contract_version.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral burden. It discloses the exact returned fields and clarifies the meaning of each version (PyPI, NetLogger API, contract), which adds useful context. It does not explicitly state read-only nature, auth requirements, or rate limits, but the read-only retrieval behavior is strongly implied and no contradiction exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two compact sentences plus a structured return list. It is front-loaded with the core purpose and wastes no words. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (zero parameters) and the presence of an output schema, the description is nearly complete. It explains what is returned even though the output schema covers this, and it clearly defines the tool's scope. The only minor gap is the absence of explicit usage guidance, which is largely inferable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. No parameter semantics need to be explained, and the description appropriately omits parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Get) and resource (version info), and precisely enumerates the three version types: the MCP version, the NetLogger API version, and the record version. It clearly distinguishes this informational tool from all operational siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance is provided. However, for a zero-parameter version retrieval tool, the usage is strongly implied: call it when version metadata is needed. No alternatives exist among siblings, so the lack of routing guidance is not critical.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

netlogger_active_netsNetlogger Active NetsC

List nets on the air now.

ParametersJSON Schema
NameRequiredDescriptionDefault
name_likeNoOnly nets whose name contains this text, ignoring case (e.g. OMISS). Empty for all.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state that this is a read-only operation, nor describe freshness/latency of the 'now' data or how filtering interacts with the live set. Only the temporal scope is conveyed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with no padding, and the key scope constraint ('now') is front-loaded. It is arguably under-specified rather than over-written, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one optional param, output schema present, so return format need not be explained), and the description covers the core purpose. However, with no annotations it should say more about safety/behavior to be complete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single name_like parameter is fully documented with case-insensitivity and empty-string semantics in the schema. The description adds nothing beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (nets) with a temporal scope qualifier ('on the air now') that implicitly distinguishes it from netlogger_past_nets. It does not name the sibling, but the active-vs-past contrast is inferable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance or mention of alternatives such as netlogger_past_nets or netlogger_checkins. The phrase 'on the air now' hints at the active filter, but the agent is left to infer when this tool is preferred over its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

netlogger_checkinsNetlogger CheckinsA

Get a live net's check-in list, and the pointer: the serial number of the station net control is working now.

ParametersJSON Schema
NameRequiredDescriptionDefault
net_nameYesThe net's name, from netlogger_active_nets.
server_nameYesThe net's server, from netlogger_active_nets (e.g. NETLOGGER2).

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden; it tells the agent this is a read operation ('Get') and that the result includes a check-in list plus a live pointer. However, it does not explicitly state read-only safety, permissions, rate limits, or whether the data changes during the net, so significant behavioral gaps remain.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence with no padding; it states the action, resource, and a key output field directly. The colon construction is slightly unusual but does not waste words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity, 100% schema coverage, and the presence of an output schema, the description covers the core purpose and the pointer field adequately. It is weaker on routing to sibling tools and omits explicit read-only/permission context, but the structured fields fill most gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has full description coverage for both required parameters, including their source (netlogger_active_nets), so the baseline is 3. The description adds no parameter syntax or source detail beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') and resource ('a live net's check-in list'), and it names the non-obvious pointer output. The word 'live' implicitly distinguishes it from netlogger_past_checkins, so an agent can tell it apart from the past-net siblings without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'a live net's' scopes usage to currently running nets, implicitly contrasting with netlogger_past_checkins, but no alternative tool is named and no explicit when/when-not or prerequisite is stated. This is implied usage rather than clear routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

netlogger_past_checkinsNetlogger Past CheckinsB

Get a closed net's check-in list.

ParametersJSON Schema
NameRequiredDescriptionDefault
net_idYesThe net ID, from netlogger_past_nets.
net_nameYesThe net's name, from netlogger_past_nets.
server_nameYesThe net's server, from netlogger_past_nets.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a read operation, but the description does not explicitly state read-only behavior, side effects, authentication needs, or pagination. The output schema covers return values, but the safety profile remains unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It is appropriately sized for a simple retrieval tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema exists, so return values need not be explained, and parameter descriptions already link the inputs to netlogger_past_nets. However, the description lacks explicit usage routing and behavioral context, leaving a gap for an agent deciding between this and netlogger_checkins.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters in detail. The description adds no parameter semantics beyond the schema, making the baseline of 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get') and resource ('closed net's check-in list'), making the scope clear. It implicitly distinguishes past from active nets, but does not explicitly name the sibling tool netlogger_checkins as the active-net alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'closed net's' versus active nets, but the description gives no explicit when-to-use, when-not-to-use, or alternative-tool guidance. It relies on the agent to infer routing from the sibling list and the word 'closed'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

netlogger_past_netsNetlogger Past NetsA

List closed nets over the last few days, with the net IDs netlogger_past_checkins needs.

ParametersJSON Schema
NameRequiredDescriptionDefault
name_likeNoOnly nets whose name contains this text (e.g. OMISS).
interval_daysNoHow many days back (default 7). Over 7 needs name_like (NetLogger's rule).

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a read-only operation and it discloses closed-net and time-window scope, but it does not explicitly state safety, permissions, or rate-limit behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is a single front-loaded sentence with no wasted words. It states the purpose, scope, and downstream linkage efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low parameter count, full schema coverage, and the presence of an output schema, the description is nearly complete: it explains what the tool returns and why it matters. It could more explicitly route the agent away from netlogger_active_nets, but no critical information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters in detail, including defaults and the NetLogger rule about intervals over 7 days. The description adds no parameter-level semantics beyond what the schema provides, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('List'), resource ('closed nets'), and time scope ('over the last few days'), and distinguishes itself from the active-nets sibling. It also clarifies the downstream use by tying the output to netlogger_past_checkins.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: use it to get closed net IDs needed by netlogger_past_checkins. It does not explicitly say when not to use it or name an alternative like netlogger_active_nets, but the closed vs. active distinction is implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

netlogger_set_callsignNetlogger Set CallsignA

Save the user's amateur radio callsign. Needed once, before the first lookup.

NetLogger is told which station is asking, in every request, so it can tell one user from another. Ask the user for their own callsign; don't guess it.

ParametersJSON Schema
NameRequiredDescriptionDefault
callsignYesThe user's callsign (e.g. KI7MT).

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It usefully explains why the call is required (NetLogger identifies the station on every request), but does not disclose persistence, whether a repeat call overwrites the prior value, or error behavior for an invalid callsign. Return values are covered by the output schema, so that gap is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the action and the 'needed once, before the first lookup' constraint. Every sentence carries information; nothing is restated from the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter configuration tool with an output schema and full schema coverage, the description supplies the missing pieces: necessity, ordering relative to other calls, and argument sourcing. Only the overwrite/repeat-call behavior is left unspecified, a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description adds genuine value by telling the agent the value must come from the user rather than be inferred or guessed. It does not add format/validation rules beyond the schema's example (KI7MT), which keeps it just short of the top score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Save') and resource ('the user's amateur radio callsign'), which cleanly separates it from the read-only lookup siblings (netlogger_active_nets, netlogger_checkins, etc.). An agent can identify this as the one write/configuration tool in the set without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the timing and necessity: 'Needed once, before the first lookup,' plus a directive on value sourcing ('Ask the user for their own callsign; don't guess it'). This gives the agent both when to call it and how to obtain the argument, with no ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.1.0
    • First observedget_version_info
    • First observednetlogger_active_nets
    • First observednetlogger_checkins
    • First observednetlogger_past_checkins
    • First observednetlogger_past_nets
    • First observednetlogger_set_callsign

TDQS

A3.7/5.0

Scored across 6 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: version info, user setup, active nets, live check-ins, past nets, and past check-ins. No two tools overlap in function, and descriptions make the active/live vs past/closed distinction explicit.

Naming Consistency4/5

All tool names use snake_case, and five of six follow a netlogger_verb_noun pattern. The lone get_version_info breaks the prefix convention, but the deviation is minor and doesn't hinder readability.

Tool Count5/5

Six tools is a well-scoped set for a read-only NetLogger client, covering setup, discovery, and retrieval for both active and past nets. Each tool earns its place without redundancy.

Completeness4/5

The surface covers version info, user identification, active/past net listing, and check-in retrieval, which is a complete read lifecycle. However, there is no tool to submit a check-in or retrieve detailed net metadata, which may be a gap depending on intended use.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    MCP server for ARRL Logbook of The World (LoTW) that enables querying confirmations, uploaded QSOs, DXCC credits, and user activity through any MCP-compatible AI assistant. Part of the qso-graph project, it is read-only and requires LoTW credentials for authenticated tools.
    6
    1
    GPL 3.0
  • F
    license
    Not graded
    quality
    D
    maintenance
    MCP server that provides read-only access to cached metadata of public activities, contests, and competitions from multiple sources via SQLite, enabling search and listing without hitting external sites.
    1
    -