hamqth-mcp¶

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¶

uvx hamqth-mcp            # run it; nothing to install

Tools¶

Tool	Auth	Description
`hamqth_lookup`	Yes	Callsign lookup (name, grid, DXCC, coordinates, QSL preferences)
`hamqth_dxcc`	No	Resolve DXCC entity from callsign or ADIF code
`hamqth_bio`	Yes	Fetch operator biography
`hamqth_activity`	Yes	Recent DX cluster, RBN, and logbook activity
`hamqth_dx_spots`	No	Live DX cluster spots — filter by band and/or callsign
`hamqth_rbn`	No	Reverse Beacon Network decodes — filter by band, mode, continent, callsign
`hamqth_verify_qso`	No	Verify a QSO via HamQTH SAVP protocol
`get_version_info`	No	Service 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:

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

# A persona (your callsign and the dates it covers), then HamQTH for it
qso-auth persona add --name ki7mt --callsign KI7MT --start 2020-01-01
qso-auth provider enable ki7mt hamqth
qso-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):

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

Claude Code¶

Add to .claude/settings.json:

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

ChatGPT Desktop¶

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

Cursor¶

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

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

VS Code / GitHub Copilot¶

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

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

Gemini CLI¶

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

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

HAMQTH_MCP_MOCK=1 hamqth-mcp

MCP Inspector¶

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

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

Development¶

git clone https://github.com/qso-graph/hamqth-mcp.git
cd hamqth-mcp
uv sync --group dev
uv 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

Tool Reference¶

Generated from the released server's own tool definitions.

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.

No parameters.

hamqth_activity¶

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

Parameter	Type	Required	Default	Description
`persona`	string	Yes		Persona name configured in adif-mcp.
`callsign`	string	Yes		Callsign to check.

hamqth_bio¶

Fetch an operator's biography from HamQTH.

Parameter	Type	Required	Default	Description
`persona`	string	Yes		Persona name configured in adif-mcp.
`callsign`	string	Yes		Callsign to look up.

hamqth_dx_spots¶

Live DX cluster spots from HamQTH (public, no auth required).

Spots update every ~15 seconds. Max 200 spots per request.

Parameter	Type	Required	Default	Description
`limit`	integer	No	`60`	Number of spots to return (default 60, max 200).
`band`	string	No	`null`	Optional ADIF band filter (e.g., "20M", "40M").
`call`	string	No	`null`	Optional callsign filter — matches spotted call or spotter (case-insensitive, e.g., "3Y0K"). Pulls max spots and filters client-side since the API does not support server-side filtering.

hamqth_dxcc¶

Resolve a DXCC entity from a callsign or ADIF entity code.

Public endpoint — no authentication required.

Parameter	Type	Required	Default	Description
`query`	string	Yes		Callsign (e.g., VP8PJ) or ADIF entity code (e.g., 291).

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.

Parameter	Type	Required	Default	Description
`persona`	string	Yes		Persona name configured in adif-mcp.
`callsign`	string	Yes		Callsign to look up (e.g., OK2CQR).

hamqth_rbn¶

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

Parameter	Type	Required	Default	Description
`band`	string	No	`null`	ADIF band numbers, comma-separated (e.g., "20,40").
`mode`	string	No	`null`	Filter by mode (CW, RTTY, PSK31, PSK63).
`cont`	string	No	`null`	Filter by spotted station's continent (e.g., "EU", "NA").
`fromcont`	string	No	`null`	Filter by receiver/skimmer continent.
`age`	integer	No	`null`	Maximum age in seconds.
`call`	string	No	`null`	Optional callsign filter — matches spotted station (case-insensitive, e.g., "3Y0K"). Filtered client-side.

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.

Parameter	Type	Required	Description
`mycall`	string	Yes	Your callsign (e.g., "KI7MT").
`hiscall`	string	Yes	Other station's callsign (e.g., "OK2CQR").
`date`	string	Yes	QSO date in YYYYMMDD format (e.g., "20260305").
`band`	string	Yes	Band (e.g., "20M", "40M").