Documentation for pota-mcp v0.7.1. Source at v0.7.1.

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

Install​

Tools​

Quick Start​

Configure your MCP client​

Claude Desktop​

Claude Code​

ChatGPT Desktop​

Cursor​

VS Code / GitHub Copilot​

Gemini CLI​

Ask questions​

Testing Without Network​

MCP Inspector​

Development​

License​