Metadata-Version: 2.4
Name: clublog-mcp
Version: 0.1.0
Summary: MCP server for Club Log — log search, DXCC status, most-wanted rankings, OQRS
Project-URL: Homepage, https://qso-graph.io/
Project-URL: Repository, https://github.com/qso-graph/clublog-mcp
Project-URL: Issues, https://github.com/qso-graph/clublog-mcp/issues
Author: Greg Beam, KI7MT
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: amateur-radio,club-log,dxcc,ham-radio,mcp,model-context-protocol,most-wanted,oqrs,qso
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

# clublog-mcp

MCP server for [Club Log](https://clublog.org/) — DXCC entity resolution, expedition log search, propagation activity, Most Wanted rankings, and real-time callsign monitoring through any MCP-compatible AI assistant.

Part of the [qso-graph](https://qso-graph.io/) project. Operated by Michael Wells, G7VJR.

## Install

```bash
pip install clublog-mcp
```

## Tools

| Tool | Auth | Description |
|------|------|-------------|
| `clublog_dxcc` | API key | Resolve callsign to DXCC entity (date-aware for prefix changes) |
| `clublog_search` | API key | Search expedition/public logs ("am I in the log?") |
| `clublog_activity` | API key | Hour-by-hour propagation between two DXCC entities |
| `clublog_most_wanted` | Public | Current Most Wanted DXCC entity list |
| `clublog_expeditions` | Public | Active/recent expedition list with QSO counts |
| `clublog_watch` | API key | Real-time 24h activity monitor for a callsign |

## Quick Start

### 1. Get an API key

Request an application API key at [clublog.org/requestapikey.php](https://clublog.org/requestapikey.php). This is a per-application key (40-character hex), not a per-user credential.

**Important**: API keys are auto-revoked if found in public repos (GitHub scanning active).

### 2. Set the environment variable

```bash
export CLUBLOG_API_KEY=your-40-char-hex-key
```

Two tools (`clublog_most_wanted` and `clublog_expeditions`) work without an API key.

### 3. Configure your MCP client

#### Claude Desktop

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

```json
{
  "mcpServers": {
    "clublog": {
      "command": "clublog-mcp",
      "env": {
        "CLUBLOG_API_KEY": "your-40-char-hex-key"
      }
    }
  }
}
```

#### Claude Code

Add to `.claude/settings.json`:

```json
{
  "mcpServers": {
    "clublog": {
      "command": "clublog-mcp",
      "env": {
        "CLUBLOG_API_KEY": "your-40-char-hex-key"
      }
    }
  }
}
```

#### ChatGPT Desktop

```json
{
  "mcpServers": {
    "clublog": {
      "command": "clublog-mcp",
      "env": {
        "CLUBLOG_API_KEY": "your-40-char-hex-key"
      }
    }
  }
}
```

#### Cursor

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

```json
{
  "mcpServers": {
    "clublog": {
      "command": "clublog-mcp",
      "env": {
        "CLUBLOG_API_KEY": "your-40-char-hex-key"
      }
    }
  }
}
```

#### VS Code / GitHub Copilot

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

```json
{
  "servers": {
    "clublog": {
      "command": "clublog-mcp",
      "env": {
        "CLUBLOG_API_KEY": "your-40-char-hex-key"
      }
    }
  }
}
```

#### Gemini CLI

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

```json
{
  "mcpServers": {
    "clublog": {
      "command": "clublog-mcp",
      "env": {
        "CLUBLOG_API_KEY": "your-40-char-hex-key"
      }
    }
  }
}
```

### 4. Ask questions

> "What DXCC entity is 3Y0J?"

> "Am I in the 3Y0J expedition log? Search for KI7MT"

> "Show me propagation activity between USA (291) and Japan (339)"

> "What are the top 10 Most Wanted DXCC entities?"

> "What expeditions are currently active on Club Log?"

> "Is 3Y0J still on the air? Show me their 24-hour activity"

## Rate Limiting

Club Log has no published rate limits, but enforcement is real and automatic. clublog-mcp protects you:

- 500ms minimum delay between all API calls
- Token bucket: 30 requests/minute
- 3600s freeze on HTTP 403 (IP ban detection)
- Response caching (DXCC: 1hr, Most Wanted: 24hr, Activity: 1hr, Watch: 5min)

**Never** loop over `/dxcc` for batch resolution — Club Log provides `/bulkdxcc` for that (future v2.0 feature).

## Band Normalization

Club Log uses bare numbers for bands. clublog-mcp normalizes all responses to ADIF names:

| Club Log | clublog-mcp |
|----------|-------------|
| `"20"` | `"20m"` |
| `"40"` | `"40m"` |
| `"C"` | `"CW"` |
| `"P"` | `"Phone"` |
| `"D"` | `"Data"` |

## Testing Without an API Key

Set the mock environment variable to test all 6 tools:

```bash
CLUBLOG_MCP_MOCK=1 clublog-mcp
```

## MCP Inspector

```bash
CLUBLOG_API_KEY=your-key clublog-mcp --transport streamable-http --port 8003
```

## Development

```bash
git clone https://github.com/qso-graph/clublog-mcp.git
cd clublog-mcp
pip install -e .
```

## License

GPL-3.0-or-later
