mcp server

iota-mcp

MCP server for Islands on the Air — lookup, search, nearby, DXCC. Stats

qso-graph/iota-mcpcommunitylistedunreviewednot running here yet

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

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

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 14, 2026

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