Hamqth Mcp

hamqth-mcp

适用于 HamQTH.com 的 MCP 服务，可通过任何兼容 MCP 的 AI 助手查询呼号、DX 集群电台报告、Reverse Beacon Network、解析 DXCC 等。

这是 qso-graph 项目的一部分。需要身份验证的工具使用 qso-graph-auth 管理身份和凭据。

安装

uvx hamqth-mcp            # run it; nothing to install

工具

工具	身份验证	描述
hamqth_lookup	是	查询呼号（姓名、网格、DXCC、坐标、QSL 偏好）
hamqth_dxcc	否	根据呼号或 ADIF 代码解析 DXCC 实体
hamqth_bio	是	获取操作员简介
hamqth_activity	是	获取近期 DX 集群、RBN 和日志活动
hamqth_dx_spots	否	实时 DX 集群电台报告——按波段和／或呼号筛选
hamqth_rbn	否	Reverse Beacon Network 解码结果——按波段、模式、大洲和呼号筛选
hamqth_verify_qso	否	通过 HamQTH SAVP 协议验证 QSO
get_version_info	否	服务版本 + 上游 HamQTH API 版本（服务集群身份认证）

快速开始

1. 创建免费的 HamQTH 账户

在 hamqth.com 注册——完全免费，无需订阅。

2. 设置凭据

hamqth-mcp 使用 qso-graph-auth 身份管理凭据：

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

三个步骤缺一不可：如果不执行 provider enable，服务会报告该身份没有 hamqth 引用。

3. 配置 MCP 客户端

hamqth-mcp 适用于任何兼容 MCP 的客户端。添加服务配置并重启——工具会自动显示。

Claude Desktop

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

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

Claude Code

添加到 .claude/settings.json：

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

ChatGPT Desktop

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

Cursor

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

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

VS Code / GitHub Copilot

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

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

Gemini CLI

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

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

4. 提出问题

“查询呼号 OK2CQR”

“VP8PJ 属于哪个 DXCC 实体？”

“显示 OK2CQR 的简介”

“KI7MT 最近有哪些活动？”

“显示 3Y0K 的 DX 电台报告”

“3Y0K 在 CW 模式下有哪些 RBN 解码结果？”

“显示 20m 的 DX 电台报告”

“验证我在 3 月 5 日于 20m 波段与 OK2CQR 的 QSO”

无凭据测试

DXCC 工具（hamqth_dxcc）无需任何凭据即可使用——它使用公共端点。

如需在没有 HamQTH 账户的情况下测试所有工具：

HAMQTH_MCP_MOCK=1 hamqth-mcp

MCP Inspector

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

然后在 http://localhost:8005 打开 MCP Inspector。

开发

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

已知问题

• 会话： HamQTH 的 XML 会话会在一小时后过期。服务会在 55 分钟后重新登录，因此长时间运行的会话不会遇到已过期的会话。

许可证

GPL-3.0-or-later