Iota Mcp

io.github.qso-graphPublished by GitHub account qso-graphv0.4.1Updated Nov 3, 2026

Islands on the Air MCP server. Group lookup, island search, DXCC mapping, nearby groups.

VerifiedSTDIODesktop onlyLocation & LifestyleKnowledge & Memory

Overview

AI-generated overview

Read-only MCP server for Islands on the Air (IOTA) data: group lookup, island search, DXCC mapping, nearby groups and programme statistics.

What you can do
  • Look up an IOTA group by reference number and get its name, DXCC entity, bounding box, center coordinates, credit percentage and island count
  • Search IOTA groups and island names, with results deduplicated by reference number
  • List the full subgroup and island hierarchy of a group
  • Map DXCC entities to IOTA groups in both directions
  • Find IOTA groups nearest to a latitude/longitude location by great-circle distance
  • Report programme statistics and check service and upstream data versions
When to use it
Useful for radio amateurs and award chasers who want an assistant to answer questions about IOTA references, DXCC mappings, islands in a group, or which IOTA groups lie near a given place.
Requirements
Runs locally as a stdio process, launched with uvx from the iota-mcp PyPI package, so a Python/uv runtime is needed. No authentication or credentials. Network access is required to download the public IOTA JSON data, which is cached for 24 hours; a mock mode exists for offline testing.
Before you install
Read-only lookups; no data is written or sent to third parties beyond fetching the public IOTA data files. Data is cached for 24 hours, so answers may lag the daily upstream refresh.

Installation

In SourceWeft

  1. Open Iota Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
uvx iota-mcp            # run it; nothing to install

Tools

ToolDescription
iota_lookupLook up an IOTA group by reference number (e.g., NA-005)
iota_searchSearch groups and islands by name (e.g., Hawaii, Shetland)
iota_islandsList all islands and subgroups in an IOTA group
iota_dxccBidirectional DXCC-to-IOTA mapping
iota_statsProgramme summary — totals by continent, most/least credited
iota_nearbyFind IOTA groups nearest to a lat/lon location
get_version_infoService 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):

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

Add to .claude/settings.json:

json
{  "mcpServers": {    "iota": {      "command": "uvx",      "args": ["iota-mcp"]    }  }}
ChatGPT Desktop
json
{  "mcpServers": {    "iota": {      "command": "uvx",      "args": ["iota-mcp"]    }  }}
Cursor

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

json
{  "mcpServers": {    "iota": {      "command": "uvx",      "args": ["iota-mcp"]    }  }}
VS Code / GitHub Copilot

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

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

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

json
{  "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

bash
IOTA_MCP_MOCK=1 iota-mcp

MCP Inspector

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

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

Development

bash
git clone https://github.com/qso-graph/iota-mcp.gitcd iota-mcpuv sync --group devuv run pytest

License

GPL-3.0-or-later

Source: README.md at commit a3694fd

Tools

7

get_version_info

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.

Takes no parameters.

iota_lookup

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.

Parametersrefnorequired

iota_islands

Iota Islands

List all islands and subgroups in an IOTA group. Returns the full hierarchy: subgroups containing individual islands.

Parametersrefnorequired

iota_dxcc

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.

Parametersrefnodxcc_num

iota_stats

Iota Stats

Get IOTA programme summary statistics. Returns total groups and islands, breakdown by continent, DXCC entity count, and most/least credited groups.

Takes no parameters.

iota_nearby

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.

Parameterslimitlatituderequiredlongituderequired

Version history

10
  1. v0.4.1LatestOct 29, 2026
  2. v0.3.0Oct 26, 2026
  3. v0.2.3Oct 26, 2026
  4. v0.2.1Oct 26, 2026
  5. v0.2.0Oct 12, 2026
  6. v0.1.6Oct 11, 2026
  7. v0.1.5Oct 7, 2026
  8. v0.1.4Oct 6, 2026
  9. v0.1.3Sep 29, 2026
  10. v0.1.0Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts