clublog-mcp 0.1.0

MCP server for Club Log — log search, DXCC status, most-wanted rankings, OQRS

clublog-mcp

MCP server for Club Log — 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 project. Operated by Michael Wells, G7VJR.

Install

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

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

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

Claude Code

Add to .claude/settings.json:

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

ChatGPT Desktop

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

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

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

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

CLUBLOG_MCP_MOCK=1 clublog-mcp

MCP Inspector

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

Development

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

License

GPL-3.0-or-later