Hamqth Mcp

io.github.qso-graph由 GitHub 账号 qso-graph 发布v0.7.1更新于 Nov 3, 2026

HamQTH.com MCP server. Free callsign lookup, DX spots, RBN data, SAVP verification.

已验证STDIO仅桌面位置与生活网页搜索与抓取

概览

AI 生成的概览

面向 HamQTH.com 的本地 MCP 服务器，让助手查询业余无线电呼号、解析 DXCC 实体，并获取实时 DX 集群 spot 与 RBN 解码。

可以做什么
  • 查询呼号，获取姓名、网格、DXCC、坐标和 QSL 偏好，并读取操作员简介
  • 根据呼号或 ADIF 实体代码解析 DXCC 实体
  • 读取实时 DX 集群 spot 与 Reverse Beacon Network 解码，可按波段、模式、大洲或呼号筛选
  • 查看某呼号的近期 DX 集群、RBN 和日志活动
  • 通过 HamQTH SAVP 协议核验 QSO
  • 报告服务器版本与上游 HamQTH API 版本，便于多部署比对
适用场景
适合业余无线电爱好者，以及需要处理呼号、DXCC 数据、DX spotting 或 QSO 确认的助手场景，让答案来自 HamQTH 而非通用知识。
运行要求
以 Python 包形式通过 uvx 在本地运行。呼号查询、简介和活动工具需要免费的 HamQTH 账户，凭据通过 qso-graph-auth 的 persona 管理，需先安装并为 hamqth 提供方启用。DXCC、spot、RBN 和 QSO 核验使用公开端点。需要能访问 HamQTH 的网络。
安装前请注意
查询、简介和活动工具需要经 qso-graph-auth 保存的 HamQTH 用户名和密码，应将该凭据存储视为敏感信息。呼号查询和 QSO 细节会发送至 HamQTH.com。另有无需账户的模拟模式可用于测试。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Hamqth Mcp，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

hamqth-mcp

[PyPI] [MCP Registry]

MCP server for HamQTH.com — callsign lookup, DX cluster spots, Reverse Beacon Network, DXCC resolution, and more through any MCP-compatible AI assistant.

Part of the qso-graph project. Authenticated tools use qso-graph-auth for persona and credential management.

Install

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

Tools

ToolAuthDescription
hamqth_lookupYesCallsign lookup (name, grid, DXCC, coordinates, QSL preferences)
hamqth_dxccNoResolve DXCC entity from callsign or ADIF code
hamqth_bioYesFetch operator biography
hamqth_activityYesRecent DX cluster, RBN, and logbook activity
hamqth_dx_spotsNoLive DX cluster spots — filter by band and/or callsign
hamqth_rbnNoReverse Beacon Network decodes — filter by band, mode, continent, callsign
hamqth_verify_qsoNoVerify a QSO via HamQTH SAVP protocol
get_version_infoNoService version + upstream HamQTH API version (fleet identity attestation)

Quick Start

1. Create a free HamQTH account

Sign up at hamqth.com — it's free, no subscription required.

2. Set up credentials

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

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

3. Configure your MCP client

hamqth-mcp works with any MCP-compatible client. Add the server config and restart — tools appear automatically.

Claude Desktop

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

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

Add to .claude/settings.json:

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

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

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

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

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

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

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

4. Ask questions

"Look up the callsign OK2CQR"

"What DXCC entity is VP8PJ?"

"Show me the biography for OK2CQR"

"What's the recent activity for KI7MT?"

"Show me DX spots for 3Y0K"

"What RBN decodes are there for 3Y0K on CW?"

"Show me 20m DX spots"

"Verify my QSO with OK2CQR on 20m on March 5"

Testing Without Credentials

The DXCC tool (hamqth_dxcc) works without any credentials — it uses a public endpoint.

For testing all tools without a HamQTH account:

bash
HAMQTH_MCP_MOCK=1 hamqth-mcp

MCP Inspector

bash
hamqth-mcp --transport streamable-http --port 8005

Then open the MCP Inspector at http://localhost:8005.

Development

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

Known Quirks

  • Sessions: HamQTH's XML sessions expire after an hour. The server signs in again after 55 minutes, so a long-running session never sees an expired one.

License

GPL-3.0-or-later

来源：README.md，提交 86323b7

工具

8

get_version_info

Get Version Info

Get hamqth-mcp service version and upstream HamQTH API version. Returns the running PyPI version of hamqth-mcp and the HamQTH.com API contract 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.

无需输入参数。

hamqth_lookup

Hamqth Lookup

Look up a callsign on HamQTH (free, no subscription required). Returns name, grid, DXCC, coordinates, QSL preferences, and more. Field availability depends on what the operator has published.

输入参数persona必填callsign必填

hamqth_dxcc

Hamqth Dxcc

Resolve a DXCC entity from a callsign or ADIF entity code. Public endpoint — no authentication required.

输入参数query必填

hamqth_bio

Hamqth Bio

Fetch an operator's biography from HamQTH.

输入参数persona必填callsign必填

hamqth_activity

Hamqth Activity

Get recent DX cluster, RBN, and logbook activity for a callsign.

输入参数persona必填callsign必填

hamqth_dx_spots

Hamqth Dx Spots

Live DX cluster spots from HamQTH (public, no auth required). Spots update every ~15 seconds. Max 200 spots per request.

输入参数bandcalllimit

hamqth_rbn

Hamqth Rbn

Reverse Beacon Network spots from HamQTH (public, no auth required).

输入参数agebandcallcontmodefromcont

hamqth_verify_qso

Hamqth Verify Qso

Verify a QSO via HamQTH SAVP protocol (public, no auth required). Checks if a QSO exists in HamQTH's database for both parties.

输入参数band必填date必填mycall必填hiscall必填

版本历史

11
  1. v0.7.1最新Oct 29, 2026
  2. v0.6.0Oct 26, 2026
  3. v0.5.3Oct 26, 2026
  4. v0.5.1Oct 26, 2026
  5. v0.5.0Oct 12, 2026
  6. v0.4.6Oct 11, 2026
  7. v0.4.5Oct 7, 2026
  8. v0.4.4Oct 6, 2026
  9. v0.4.3Oct 4, 2026
  10. v0.4.2Sep 29, 2026
  11. v0.2.0Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分