Lotw Mcp

io.github.qso-graphPublished by GitHub account qso-graphv0.6.2Updated Nov 3, 2026

ARRL Logbook of The World MCP server. QSO query, QSL status, DXCC credit tracking.

VerifiedSTDIODesktop onlyLocation & LifestyleData & Analytics

Overview

AI-generated overview

Read-only MCP server for ARRL Logbook of The World that lets an assistant query QSOs, QSL confirmations, DXCC credits and callsign activity.

What you can do
  • Query confirmed QSL records with band, mode, call and date filters
  • Query all uploaded QSOs, confirmed and unconfirmed
  • Query DXCC award credits from LoTW confirmations
  • Download the full log as raw ADIF text, optionally confirmed QSLs only
  • Check whether a callsign uses LoTW and when it last uploaded
  • Report service and upstream LoTW schema versions
When to use it
Useful for amateur radio operators who log in LoTW and want an assistant to answer questions about confirmations, unconfirmed QSOs, DXCC credit progress, or whether a station is active on LoTW.
Requirements
Runs locally as a Python package via uvx (uv required). Credentialed tools need qso-graph-auth installed, a persona with a callsign and date range, the lotw provider enabled, and LoTW username and password stored there. The user activity tool needs no credentials. Network access to LoTW is required.
Before you install
Stores LoTW username and password through qso-graph-auth; treat that store as sensitive. Read-only by design, with no uploads. Large queries can take 30-60 seconds. The user activity tool uses a locally cached public CSV refreshed weekly, so results may lag.

Installation

In SourceWeft

  1. Open Lotw 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

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

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

Tools

ToolAuthDescription
lotw_confirmationsYesQuery confirmed QSLs with band/mode/call/date filters
lotw_qsosYesQuery all uploaded QSOs (confirmed and unconfirmed)
lotw_dxcc_creditsYesDXCC award credits from LoTW confirmations
lotw_downloadYesDownload QSOs as ADIF file
lotw_user_activityNoCheck if a callsign uses LoTW and when they last uploaded
get_version_infoNoService version + upstream LoTW schema version (fleet identity attestation)

Quick Start

1. Set up credentials

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

bash
# Install qso-graph-auth if you haven'tuv tool install qso-graph-auth
# A persona (your callsign and the dates it covers), then LoTW for itqso-graph-auth persona add --name ki7mt --callsign KI7MT --start 2020-01-01qso-graph-auth provider enable ki7mt lotwqso-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):

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

Add to .claude/settings.json:

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

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

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

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

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

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

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

bash
LOTW_MCP_MOCK=1 lotw-mcp

Performance Notes

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

MCP Inspector

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

Development

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

License

GPL-3.0-or-later

Source: README.md at commit c22d459

Tools

6

get_version_info

Get Version Info

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.

Takes no parameters.

lotw_confirmations

Lotw Confirmations

Query confirmed QSL records from LoTW.

Parametersbanddxccmodesincedetailpersonarequiredcallsign

lotw_qsos

Lotw Qsos

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

Parametersbandmodesincepersonarequiredend_datestart_date

lotw_dxcc_credits

Lotw Dxcc Credits

Query DXCC award credits from LoTW confirmations.

Parametersentitypersonarequired

lotw_download

Lotw Download

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

Parametersbandmodesincepersonarequiredqsl_only

lotw_user_activity

Lotw User Activity

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

Parameterscallsignrequired

Version history

11
  1. v0.6.2LatestOct 29, 2026
  2. v0.5.0Oct 26, 2026
  3. v0.4.3Oct 26, 2026
  4. v0.4.1Oct 26, 2026
  5. v0.4.0Oct 12, 2026
  6. v0.3.8Oct 11, 2026
  7. v0.3.7Oct 7, 2026
  8. v0.3.6Oct 6, 2026
  9. v0.3.5Oct 4, 2026
  10. v0.3.4Sep 29, 2026
  11. v0.2.0Sep 16, 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