Skip to main content
Glama
lotw-mcp

lotw-mcp

by qso-graph

lotw-mcp

PyPI MCP Registry

MCP server for ARRL Logbook of The World (LoTW)—query confirmations, uploaded QSOs, DXCC credits, and user activity through any MCP-compatible AI assistant.

Part of the qso-graph project. Read-only—uploads require TQSL digital signatures and are out of scope.

Install

uvx lotw-mcp            # run it; nothing to install

Related MCP server: hamqth-mcp

Tools

Tool

Auth

Description

lotw_confirmations

Yes

Query confirmed QSLs with band/mode/call/date filters

lotw_qsos

Yes

Query all uploaded QSOs (confirmed and unconfirmed)

lotw_dxcc_credits

Yes

DXCC award credits from LoTW confirmations

lotw_download

Yes

Download QSOs as ADIF file

lotw_user_activity

No

Check if a callsign uses LoTW and when they last uploaded

get_version_info

No

Service version + upstream LoTW schema version (fleet identity attestation)

Quick Start

1. Set up credentials

lotw-mcp uses qso-graph-auth personas for credential management:

# Install qso-graph-auth if you haven't
uv tool install qso-graph-auth

# A persona (your callsign and the dates it covers), then LoTW for it
qso-graph-auth persona add --name ki7mt --callsign KI7MT --start 2020-01-01
qso-graph-auth provider enable ki7mt lotw
qso-graph-auth creds set ki7mt lotw      # asks for your username, then your password (hidden)

All three steps are needed: without provider enable, the server reports that the persona has no lotw ref.

Note: The LoTW login is usually your callsign but not always. Pre-Sept 2019 accounts may require lowercase passwords. Avoid special characters in passwords.

2. Configure your MCP client

Claude Desktop

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

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

Claude Code

Add to .claude/settings.json:

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

ChatGPT Desktop

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

Cursor

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

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

VS Code / GitHub Copilot

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

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

Gemini CLI

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

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

3. Ask questions

"How many LoTW confirmations did I get this month?"

"Show me all unconfirmed 20m FT8 QSOs uploaded to LoTW in the last 90 days"

"What DXCC credits do I have on 40m CW?"

"Does JA1ABC use LoTW? When did they last upload?"

Public Tool

lotw_user_activity works without any credentials. It uses the public LoTW user activity CSV, cached locally for 7 days.

Testing Without Credentials

Set the mock environment variable:

LOTW_MCP_MOCK=1 lotw-mcp

Performance Notes

LoTW can be slow (30-60 s for large queries). lotw-mcp uses 120 s timeouts. Use date filters (since, start_date) to limit result sets.

MCP Inspector

lotw-mcp --transport streamable-http --port 8004

Development

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

License

GPL-3.0-or-later

Available Tools

6 tools
get_version_infoGet Version InfoA
Read-onlyIdempotent

Get lotw-mcp service version and upstream LoTW schema version.

Returns the running PyPI version of lotw-mcp and the ARRL LoTW ADIF/CSV export schema 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.

Inputs: no named parameters. Returns: object

lotw_confirmationsLotw ConfirmationsB
Read-onlyIdempotent

Query confirmed QSL records from LoTW.

Inputs: persona (required), band, dxcc, mode, +3 more. Returns: object

lotw_downloadLotw DownloadA
Read-onlyIdempotent

Download your complete LoTW log as raw ADIF text.

Returns the .adi file content — save to disk for import into your logger. Set qsl_only=True for confirmed QSLs only. Omit 'since' for full history. Warning: large logs may take 30-60 seconds (LoTW is slow).

Inputs: persona (required), band, mode, since, +1 more. Returns: object

lotw_dxcc_creditsLotw Dxcc CreditsB
Read-onlyIdempotent

Query DXCC award credits from LoTW confirmations.

Inputs: persona (required), entity. Returns: object

lotw_qsosLotw QsosB
Read-onlyIdempotent

Query all uploaded QSOs from LoTW (confirmed and unconfirmed).

Inputs: persona (required), band, mode, since, +2 more. Returns: object

lotw_user_activityLotw User ActivityA
Read-onlyIdempotent

Check if a callsign uses LoTW and when they last uploaded.

Public endpoint — no authentication required. Uses a locally cached copy of the LoTW user activity CSV (refreshed weekly).

Inputs: callsign (required). Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation4/5

    The tools mostly target distinct LoTW resources: confirmations, DXCC credits, all QSOs, raw log download, user activity, and version info. There is mild overlap between lotw_confirmations and lotw_qsos (confirmed subset vs all QSOs), but descriptions make the boundary clear.

    Naming Consistency4/5

    Most tools use a consistent lotw_ domain prefix followed by a noun/action, e.g. lotw_confirmations, lotw_dxcc_credits, lotw_qsos. get_version_info deviates with a generic verb_noun pattern, but overall the set remains readable and predictable.

    Tool Count5/5

    Six tools is well-scoped for a LoTW query/download server. Each tool covers a distinct capability without obvious filler or missing core operations.

    Completeness4/5

    The surface covers the main read-only LoTW workflows: QSO lookup, confirmations, DXCC credits, raw ADIF download, and callsign activity. Minor gaps exist for richer award queries (e.g. WAS/WAC) or detailed per-QSO inspection, but agents can work around them with the current tools.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      An MCP server for eQSL.cc that allows users to download incoming electronic QSL cards, verify specific contacts, and check Authenticity Guaranteed status. It enables natural language interaction with amateur radio logs and confirmation records through any MCP-compatible AI assistant.
      6
      145 PyPI
      GPL 3.0
    • A
      license
      A
      quality
      A
      maintenance
      MCP server for HamQTH.com — callsign lookup, DX cluster spots, Reverse Beacon Network, DXCC resolution, and more through any MCP-compatible AI assistant.
      8
      126 PyPI
      GPL 3.0
    • A
      license
      A
      quality
      A
      maintenance
      MCP server for QRZ.com — callsign lookups, DXCC entity resolution, and logbook queries through any MCP-compatible AI assistant.
      6
      269 PyPI
      4
      GPL 3.0
    • A
      license
      A
      quality
      A
      maintenance
      Enables IOTA group lookup, island search, DXCC mapping, nearby groups, and programme statistics through any MCP-compatible AI assistant.
      7
      114 PyPI
      GPL 3.0