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_park_activations`	A park's recent activations — who, when, and QSOs by mode
`pota_park_leaderboard`	A park's top activators, activator QSOs and hunter QSOs
`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, with optional location, park, activator and time-window filters
`pota_location_parks`	All parks in a state/province/country
`pota_nearby_parks`	Find parks near a point — great for 2-fer planning
`pota_rare_parks_near`	Parks near a point that are rarely or never activated
`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_activations¶

List recent activations of a POTA park, most recent first.

Answers "when was this park last activated?" and "is it often on the air?".

Parameter	Type	Required	Default	Description
`reference`	string	Yes		Park reference code (e.g., US-0062).
`count`	integer	No	`10`	How many recent activations to return (default 10, max 50).

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_leaderboard¶

Top activators and hunters of a POTA park.

Three boards: most activations, most QSOs as an activator, most QSOs as a hunter. Each row is a callsign and a count and nothing else.

Parameter	Type	Required	Default	Description
`reference`	string	Yes		Park reference code (e.g., US-0062).
`limit`	integer	No	`10`	Rows per board (default 10, max 25). POTA currently publishes five per board, so a higher limit changes nothing until it does.

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_rare_parks_near¶

Find the least-activated POTA parks near a point.

Answers "which parks near me have never, or rarely, been activated?" — for an activator looking for something unworked, or a hunter looking for a rare one. Least activated first, nearest first among equals.

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_scheduled¶

Get upcoming scheduled POTA activations.

All filters are optional and combine with AND — omit them all and the whole schedule comes back, as before.

Parameter	Type	Required	Default	Description
`location`	string	No	`""`	Filter by location code (e.g., US-ID, CA-ON). Matches a park that spans regions, so US-MD finds a park listed as US-VA,US-MD. Empty for all.
`reference`	string	No	`""`	Filter by park reference (e.g., US-0058). Empty for all.
`activator`	string	No	`""`	Filter by activator callsign (e.g., N3VEM). Empty for all.
`within_hours`	number	No	`null`	Only activations whose start time falls between now and this many hours from now. An activation already under way is not included — pota_spots is what reports the air now. Omit for no time limit.

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