pota-mcp¶

MCP server for Parks on the Air (POTA) — live activator spots, park info, activator/hunter stats, and scheduled activations through any MCP-compatible AI assistant.

Part of the qso-graph project. No authentication required — all POTA endpoints are public.

Install¶

uvx pota-mcp            # run it; nothing to install

Tools¶

Tool	Description
`pota_spots`	Current activator spots with park/grid enrichment and optional filters
`pota_park_info`	Park details by reference code (name, grid, type, agencies, website)
`pota_park_stats`	Activation and QSO counts for a park
`pota_user_stats`	Activator/hunter stats by callsign (callsign, name, activator, attempts, hunter, awards, endorsements; no address or email-derived fields)
`pota_scheduled`	Upcoming scheduled activations
`pota_location_parks`	All parks in a state/province/country
`pota_nearby_parks`	Find parks near a point — great for 2-fer planning
`get_version_info`	Service version + upstream spec version (fleet identity attestation)

Quick Start¶

No credentials needed — just install and configure your MCP client.

Configure your MCP client¶

pota-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": {
    "pota": {
      "command": "uvx",
      "args": ["pota-mcp"]
    }
  }
}

Claude Code¶

Add to .claude/settings.json:

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

ChatGPT Desktop¶

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

Cursor¶

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

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

VS Code / GitHub Copilot¶

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

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

Gemini CLI¶

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

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

Ask questions¶

"What POTA activations are happening right now?"

"Tell me about park US-0001 — how many activations has it had?"

"What are K4SWL's POTA stats?"

"Show me all parks in Idaho"

"Are there any CW activators on 20m right now?"

"What activations are scheduled for tomorrow?"

Testing Without Network¶

For testing all tools without hitting the POTA API:

POTA_MCP_MOCK=1 pota-mcp

MCP Inspector¶

pota-mcp --transport streamable-http --port 8006

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

Development¶

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

License¶

GPL-3.0-or-later

Tool Reference¶

Generated from the released server's own tool definitions.

get_version_info¶

Get pota-mcp service version and upstream spec version.

Returns the running PyPI version of pota-mcp and the POTA API revision currently 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.

pota_location_parks¶

List all POTA parks in a state, province, or country.

Parameter	Type	Required	Default	Description
`location`	string	Yes		Location code (e.g., US-ID for Idaho, CA-ON for Ontario, G for England).

pota_nearby_parks¶

Find POTA parks near a geographic point.

Fetches all parks in the given location and filters by distance. Useful for finding 2-fer candidates near an activation site.

Parameter	Type	Required	Default	Description
`location`	string	Yes		Location code (e.g., US-ID, CA-ON). Required to scope the search.
`latitude`	number	Yes		Center point latitude (e.g., 43.617).
`longitude`	number	Yes		Center point longitude (e.g., -115.993).
`radius_km`	number	No	`50.0`	Search radius in km (default 50, max 500).
`limit`	integer	No	`25`	Maximum parks to return (default 25, max 100).

pota_park_info¶

Get detailed park information by POTA reference code.

Parameter	Type	Required	Default	Description
`reference`	string	Yes		Park reference code (e.g., US-0001, CA-5580, G-0001).

pota_park_stats¶

Get activation and QSO counts for a POTA park.

Parameter	Type	Required	Default	Description
`reference`	string	Yes		Park reference code (e.g., US-0001).

pota_scheduled¶

Get upcoming scheduled POTA activations.

No parameters.

pota_spots¶

Get current POTA activator spots.

Returns live spot feed with park details, grid squares, and coordinates. All filters are optional — omit to get all active spots.

Parameter	Type	Required	Default	Description
`band`	string	No	`""`	Filter by band (e.g., 20m, 40m). Empty for all bands.
`mode`	string	No	`""`	Filter by mode (e.g., CW, FT8, SSB). Empty for all modes.
`location`	string	No	`""`	Filter by location code (e.g., US-ID, CA-ON). Empty for all.
`program`	string	No	`""`	Filter by program prefix (e.g., US, VE, G). Empty for all.

pota_user_stats¶

Get POTA activator and hunter statistics for a callsign.

Parameter	Type	Required	Default	Description
`callsign`	string	Yes		Callsign to look up (e.g., K4SWL, KI7MT).