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 分