iota-mcp¶

MCP server for Islands on the Air (IOTA) — group lookup, island search, DXCC mapping, nearby groups, and programme statistics through any MCP-compatible AI assistant.

Part of the qso-graph project. No authentication required — all IOTA data is public.

Install¶

uvx iota-mcp            # run it; nothing to install

Tools¶

Tool	Description
`iota_lookup`	Look up an IOTA group by reference number (e.g., NA-005)
`iota_search`	Search groups and islands by name (e.g., Hawaii, Shetland)
`iota_islands`	List all islands and subgroups in an IOTA group
`iota_dxcc`	Bidirectional DXCC-to-IOTA mapping
`iota_stats`	Programme summary — totals by continent, most/least credited
`iota_nearby`	Find IOTA groups nearest to a lat/lon location
`get_version_info`	Service version + upstream programme data version (fleet identity attestation)

Quick Start¶

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

Configure your MCP client¶

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

Claude Code¶

Add to .claude/settings.json:

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

ChatGPT Desktop¶

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

Cursor¶

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

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

VS Code / GitHub Copilot¶

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

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

Gemini CLI¶

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

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

Ask questions¶

"Look up IOTA group NA-005"

"Search for islands named Shetland"

"What IOTA groups are near Boise, Idaho?"

"Show me all islands in EU-005"

"What IOTA references map to DXCC 291?"

"Give me IOTA programme statistics"

Data Source¶

Data comes from the official IOTA website JSON downloads:

fulllist.json — complete group/subgroup/island hierarchy (~1.3 MB)
dxcc_matches_one_iota.json — 1:1 DXCC-to-IOTA mapping (~3.5 KB)

Data is downloaded once and cached for 24 hours (IOTA refreshes daily at 00:00 UTC).

Testing Without Network¶

IOTA_MCP_MOCK=1 iota-mcp

MCP Inspector¶

iota-mcp --transport streamable-http --port 8010

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

Development¶

git clone https://github.com/qso-graph/iota-mcp.git
cd iota-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 iota-mcp service version and upstream programme data version.

Returns the running PyPI version of iota-mcp and the IOTA programme data revision 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.

iota_dxcc¶

Bidirectional DXCC-to-IOTA mapping.

Provide either dxcc_num to find all IOTA groups for a DXCC entity, or refno to find which DXCC entities an IOTA group belongs to.

Parameter	Type	Required	Default	Description
`dxcc_num`	string	No	`""`	DXCC entity number (e.g., 291 for USA, 223 for England).
`refno`	string	No	`""`	IOTA reference number (e.g., EU-005).

iota_islands¶

List all islands and subgroups in an IOTA group.

Returns the full hierarchy: subgroups containing individual islands.

Parameter	Type	Required	Default	Description
`refno`	string	Yes		IOTA reference number (e.g., NA-005, EU-005).

iota_lookup¶

Look up an IOTA group by reference number.

Returns group details including name, DXCC entity, bounding box, center coordinates, credit percentage, and island count.

Parameter	Type	Required	Default	Description
`refno`	string	Yes		IOTA reference number (e.g., NA-005, EU-005, AF-001).

iota_nearby¶

Find IOTA groups nearest to a location.

Computes great-circle distance from the given coordinates to the center of each IOTA group's bounding box.

Parameter	Type	Required	Default	Description
`latitude`	number	Yes		Latitude in decimal degrees (e.g., 43.6 for Boise).
`longitude`	number	Yes		Longitude in decimal degrees (e.g., -116.2 for Boise).
`limit`	integer	No	`20`	Maximum results to return (default 20).

iota_search¶

Search IOTA groups and islands by name.

Searches both group names and individual island names. Results are deduplicated by IOTA reference number.

Parameter	Type	Required	Default	Description
`query`	string	Yes		Search text (e.g., Hawaii, Shetland, Comoro).
`limit`	integer	No	`25`	Maximum results to return (default 25).

iota_stats¶

Get IOTA programme summary statistics.

Returns total groups and islands, breakdown by continent, DXCC entity count, and most/least credited groups.

No parameters.