Metadata-Version: 2.4
Name: hamqth-mcp
Version: 0.1.2
Summary: MCP server for HamQTH.com — callsign lookup (free QRZ alternative)
Project-URL: Homepage, https://qso-graph.io/
Project-URL: Repository, https://github.com/qso-graph/hamqth-mcp
Project-URL: Issues, https://github.com/qso-graph/hamqth-mcp/issues
Author: Greg Beam, KI7MT
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: amateur-radio,callsign-lookup,ham-radio,hamqth,mcp,model-context-protocol,qrz-alternative
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Ham Radio
Requires-Python: >=3.10
Requires-Dist: adif-mcp>=0.6.2
Requires-Dist: fastmcp>=3.0
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.qso-graph/hamqth-mcp -->
# hamqth-mcp

MCP server for [HamQTH.com](https://www.hamqth.com/) — free callsign lookup, DXCC resolution, biography, and recent activity through any MCP-compatible AI assistant.

Part of the [qso-graph](https://qso-graph.io/) project. Depends on [adif-mcp](https://pypi.org/project/adif-mcp/) for persona and credential management.

## Install

```bash
pip install hamqth-mcp
```

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

## Quick Start

### 1. Create a free HamQTH account

Sign up at [hamqth.com](https://www.hamqth.com/) — it's free, no subscription required.

### 2. Set up credentials

hamqth-mcp uses adif-mcp personas for credential management:

```bash
# Install adif-mcp if you haven't
pip install adif-mcp

# Create a persona and add HamQTH credentials
adif-mcp persona create ki7mt --callsign KI7MT
adif-mcp persona provider ki7mt hamqth --username KI7MT
adif-mcp persona secret ki7mt hamqth
```

### 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": "hamqth-mcp"
    }
  }
}
```

#### Claude Code

Add to `.claude/settings.json`:

```json
{
  "mcpServers": {
    "hamqth": {
      "command": "hamqth-mcp"
    }
  }
}
```

#### ChatGPT Desktop

```json
{
  "mcpServers": {
    "hamqth": {
      "command": "hamqth-mcp"
    }
  }
}
```

#### Cursor

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

```json
{
  "mcpServers": {
    "hamqth": {
      "command": "hamqth-mcp"
    }
  }
}
```

#### VS Code / GitHub Copilot

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

```json
{
  "servers": {
    "hamqth": {
      "command": "hamqth-mcp"
    }
  }
}
```

#### Gemini CLI

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

```json
{
  "mcpServers": {
    "hamqth": {
      "command": "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?"

## 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.git
cd hamqth-mcp
pip install -e .
```

## License

GPL-3.0-or-later
