Lotw Mcp

lotw-mcp

ARRL Logbook of The World（LoTW）的 MCP 服务 — 通过任何兼容 MCP 的 AI 助手查询确认记录、已上传的 QSO、DXCC 积分和用户活动。

隶属于 qso-graph 项目。仅支持读取 — 上传需要 TQSL 数字签名，不在本项目范围内。

安装

uvx lotw-mcp            # run it; nothing to install

工具

工具	认证	描述
lotw_confirmations	是	按波段／模式／呼号／日期筛选并查询已确认的 QSL
lotw_qsos	是	查询所有已上传的 QSO（已确认和未确认）
lotw_dxcc_credits	是	查询 LoTW 确认记录中的 DXCC 奖项积分
lotw_download	是	将 QSO 下载为 ADIF 文件
lotw_user_activity	否	检查某个呼号是否使用 LoTW，以及最近一次上传的时间
get_version_info	否	服务版本 + 上游 LoTW 架构版本（集群身份证明）

快速开始

1. 设置凭据

lotw-mcp 使用 qso-graph-auth personas 管理凭据：

# 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-auth persona add --name ki7mt --callsign KI7MT --start 2020-01-01
qso-auth provider enable ki7mt lotw
qso-auth creds set ki7mt lotw      # asks for your username, then your password (hidden)

这三个步骤缺一不可：如果没有执行 provider enable，服务会报告 persona 没有 lotw ref。

注意：LoTW 的 login 通常是你的呼号，但并非总是如此。2019 年 9 月之前的账户可能需要使用小写密码。请避免在密码中使用特殊字符。

2. 配置 MCP 客户端

Claude Desktop

添加到 claude_desktop_config.json（macOS 上为 ~/Library/Application Support/Claude/，Windows 上为 %APPDATA%\Claude\）：

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

Claude Code

添加到 .claude/settings.json：

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

ChatGPT Desktop

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

Cursor

添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

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

VS Code / GitHub Copilot

添加到工作区中的 .vscode/mcp.json：

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

Gemini CLI

添加到 ~/.gemini/settings.json（全局）或 .gemini/settings.json（项目级）：

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

3. 提问

“我本月获得了多少条 LoTW 确认记录？”

“列出过去 90 天内上传到 LoTW 的所有未确认 20m FT8 QSO”

“我在 40m CW 上有多少 DXCC 积分？”

“JA1ABC 使用 LoTW 吗？他们最近一次上传是什么时候？”

公共工具

lotw_user_activity 无需任何凭据即可使用。它使用公开的 LoTW 用户活动 CSV，并在本地缓存 7 天。

无凭据测试

设置模拟环境变量：

LOTW_MCP_MOCK=1 lotw-mcp

性能说明

LoTW 可能响应缓慢（大型查询需要 30-60 秒）。lotw-mcp 使用 120 秒超时。请使用日期筛选条件（since、start_date）限制结果集。

MCP Inspector

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

开发

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

许可证

GPL-3.0-or-later