Skip to main content
Glama
iota-mcp

iota-mcp

by qso-graph

iota-mcp

PyPI MCP Registry

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

Related MCP server: qrz-mcp

Tools

Tool

Description

iota_lookup

Look up an IOTA group by reference number (for example, NA-005)

iota_search

Search groups and islands by name (for example, 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

Available Tools

7 tools
get_version_infoGet Version InfoA
Read-onlyIdempotent

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.

Inputs: no named parameters. Returns: object

iota_dxccIota DxccA
Read-onlyIdempotent

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.

Inputs: refno, dxcc_num. Returns: object

iota_islandsIota IslandsA
Read-onlyIdempotent

List all islands and subgroups in an IOTA group.

Returns the full hierarchy: subgroups containing individual islands.

Inputs: refno (required). Returns: object

iota_lookupIota LookupA
Read-onlyIdempotent

Look up an IOTA group by reference number.

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

Inputs: refno (required). Returns: object

iota_nearbyIota NearbyA
Read-onlyIdempotent

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.

Inputs: latitude (required), longitude (required), limit. Returns: object

iota_statsIota StatsA
Read-onlyIdempotent

Get IOTA programme summary statistics.

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

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: version metadata, reference lookup, name search, island hierarchy, statistics, DXCC mapping, and proximity search. The only plausible overlap is lookup versus search, but they are separated by reference number versus name, and the descriptions make the boundary clear.

    Naming Consistency4/5

    Six tools share a predictable iota_ prefix and are readable together, though the pattern is noun-oriented rather than a strict verb_noun convention. get_version_info is a minor deviation as a meta tool with a different prefix, but it is clear and not confusing.

    Tool Count5/5

    Seven tools is well scoped for a read-only IOTA reference server. Each tool covers a meaningful operation, and there are no redundant or filler endpoints.

    Completeness4/5

    The surface covers lookup by reference, search by name, island hierarchy, DXCC mapping, proximity search, statistics, and version metadata. Minor gaps such as listing or filtering all groups without a name query are workable through existing search and mapping tools.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      MCP server for HamQTH.com — callsign lookup, DX cluster spots, Reverse Beacon Network, DXCC resolution, and more through any MCP-compatible AI assistant.
      8
      126 PyPI
      GPL 3.0
    • A
      license
      A
      quality
      A
      maintenance
      MCP server for QRZ.com — callsign lookups, DXCC entity resolution, and logbook queries through any MCP-compatible AI assistant.
      6
      269 PyPI
      4
      GPL 3.0
    • A
      license
      A
      quality
      A
      maintenance
      MCP server for Parks on the Air (POTA) providing live activator spots, park details, activator/hunter stats, and scheduled activations through any MCP-compatible AI assistant.
      11
      147 PyPI
      3
      GPL 3.0
    • A
      license
      B
      quality
      A
      maintenance
      MCP server for Summits on the Air (SOTA) — live spots, activation alerts, summit info, and nearby summits through any MCP-compatible AI assistant.
      5
      113 PyPI
      1
      GPL 3.0