|
| 1 | +# iota-mcp |
| 2 | + |
| 3 | +**Islands on the Air integration — group lookup, island search, DXCC mapping, nearby groups, programme statistics.** |
| 4 | + |
| 5 | +```bash |
| 6 | +pip install iota-mcp |
| 7 | +``` |
| 8 | + |
| 9 | +[GitHub](https://github.com/qso-graph/iota-mcp) · [PyPI](https://pypi.org/project/iota-mcp/) |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +## Tools |
| 14 | + |
| 15 | +All 6 tools are **public** — no credentials needed. |
| 16 | + |
| 17 | +| Tool | Description | |
| 18 | +|------|-------------| |
| 19 | +| `iota_lookup` | Look up an IOTA group by reference number | |
| 20 | +| `iota_search` | Search groups and islands by name | |
| 21 | +| `iota_islands` | List all islands and subgroups in a group | |
| 22 | +| `iota_dxcc` | Bidirectional DXCC-to-IOTA mapping | |
| 23 | +| `iota_stats` | Programme summary statistics | |
| 24 | +| `iota_nearby` | Find IOTA groups nearest to a location | |
| 25 | + |
| 26 | +--- |
| 27 | + |
| 28 | +## Tool Reference |
| 29 | + |
| 30 | +### iota_lookup |
| 31 | + |
| 32 | +Look up an IOTA group by reference number. |
| 33 | + |
| 34 | +| Parameter | Type | Required | Description | |
| 35 | +|-----------|------|:--------:|-------------| |
| 36 | +| `refno` | str | Yes | IOTA reference number (e.g., "NA-005", "EU-005", "OC-019") | |
| 37 | + |
| 38 | +Returns group name, DXCC entity, bounding box, center coordinates, credit percentage, and island count. |
| 39 | + |
| 40 | +### iota_search |
| 41 | + |
| 42 | +Search IOTA groups and islands by name. |
| 43 | + |
| 44 | +| Parameter | Type | Required | Description | |
| 45 | +|-----------|------|:--------:|-------------| |
| 46 | +| `query` | str | Yes | Search text (e.g., "Hawaii", "Shetland", "Comoro") | |
| 47 | +| `limit` | int | No | Maximum results to return (default 25) | |
| 48 | + |
| 49 | +Searches both group names and individual island names. Results are deduplicated by IOTA reference number. |
| 50 | + |
| 51 | +### iota_islands |
| 52 | + |
| 53 | +List all islands and subgroups in an IOTA group. |
| 54 | + |
| 55 | +| Parameter | Type | Required | Description | |
| 56 | +|-----------|------|:--------:|-------------| |
| 57 | +| `refno` | str | Yes | IOTA reference number (e.g., "EU-005") | |
| 58 | + |
| 59 | +Returns the full hierarchy: subgroups containing individual islands with names and IDs. |
| 60 | + |
| 61 | +### iota_dxcc |
| 62 | + |
| 63 | +Bidirectional DXCC-to-IOTA mapping. |
| 64 | + |
| 65 | +| Parameter | Type | Required | Description | |
| 66 | +|-----------|------|:--------:|-------------| |
| 67 | +| `dxcc_num` | str | No | DXCC entity number (e.g., "291" for USA, "223" for England) | |
| 68 | +| `refno` | str | No | IOTA reference number (e.g., "EU-005") | |
| 69 | + |
| 70 | +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. |
| 71 | + |
| 72 | +### iota_stats |
| 73 | + |
| 74 | +Get IOTA programme summary statistics. No parameters. |
| 75 | + |
| 76 | +Returns total groups and islands, breakdown by continent, DXCC entity count, and most/least credited groups. |
| 77 | + |
| 78 | +### iota_nearby |
| 79 | + |
| 80 | +Find IOTA groups nearest to a location. |
| 81 | + |
| 82 | +| Parameter | Type | Required | Description | |
| 83 | +|-----------|------|:--------:|-------------| |
| 84 | +| `latitude` | float | Yes | Latitude in decimal degrees (e.g., 43.6 for Boise) | |
| 85 | +| `longitude` | float | Yes | Longitude in decimal degrees (e.g., -116.2 for Boise) | |
| 86 | +| `limit` | int | No | Maximum results to return (default 20) | |
| 87 | + |
| 88 | +Returns IOTA groups sorted by great-circle distance from the given coordinates. |
| 89 | + |
| 90 | +--- |
| 91 | + |
| 92 | +## Data Source |
| 93 | + |
| 94 | +Data comes from the official [IOTA website](https://www.iota-world.org/) JSON downloads — refreshed daily at 00:00 UTC: |
| 95 | + |
| 96 | +- **fulllist.json** (~1.3 MB) — complete group/subgroup/island hierarchy (1,178 groups, 13,020 islands) |
| 97 | +- **dxcc_matches_one_iota.json** (~3.5 KB) — 1:1 DXCC-to-IOTA mapping |
| 98 | + |
| 99 | +Data is downloaded once on first use and cached in memory for 24 hours. |
| 100 | + |
| 101 | +--- |
| 102 | + |
| 103 | +## No Credential Setup Needed |
| 104 | + |
| 105 | +IOTA data is completely public. Just install and start using it — no `adif-mcp` dependency, no persona setup. |
| 106 | + |
| 107 | +--- |
| 108 | + |
| 109 | +## Mock Mode |
| 110 | + |
| 111 | +```bash |
| 112 | +IOTA_MCP_MOCK=1 iota-mcp |
| 113 | +``` |
| 114 | + |
| 115 | +## MCP Inspector |
| 116 | + |
| 117 | +```bash |
| 118 | +iota-mcp --transport streamable-http --port 8010 |
| 119 | +``` |
0 commit comments