adif-mcp¶

MCP server for the ADIF 3.1.7 specification: validate and parse ADIF records, search the spec's fields, enumerations and data types, and compute distance and heading between Maidenhead locators, through any MCP-compatible AI assistant.

Part of the qso-graph project. No authentication required — the ADIF specification is bundled, so it works offline.

Install¶

uvx adif-mcp            # run it; nothing to install

Tools¶

Tool	Description	Key Parameters
`validate_adif_record`	Validate a raw ADIF record against the 3.1.7 spec	adif_string
`parse_adif`	Streaming parser for large ADIF files, with pagination	file_path, start_at, limit
`read_specification_resource`	Raw JSON for any spec module (band, mode, fields, ...)	resource_name
`list_enumerations`	All ADIF enumerations with entry counts	—
`search_enumerations`	Search enumeration records by keyword	search_term, enumeration
`calculate_distance`	Great-circle distance (km) between two Maidenhead locators	start, end
`calculate_heading`	Initial beam heading (azimuth) between two locators	start, end
`get_version_info`	Service version + upstream spec version (fleet identity attestation)	—

What is ADIF?¶

ADIF (Amateur Data Interchange Format) is the standard file format amateur radio logging programs use to exchange QSO records. adif-mcp is the specification package of qso-graph: it validates, parses and searches ADIF so an assistant can work with logs safely and accurately. Credentials are handled separately by qso-graph-auth, and each logging service has its own MCP server (see qso-graph.io).

Quick Start¶

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

Configure your MCP client¶

adif-mcp works with any MCP-compatible client. Add the server config and restart. The tools appear automatically.

Claude Desktop¶

Add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

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

Claude Code¶

Add to .claude/settings.json:

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

ChatGPT Desktop¶

Configure via Settings > Apps & Connectors, or in your agent definition:

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

Cursor¶

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

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

VS Code / GitHub Copilot¶

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

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

Gemini CLI¶

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

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

Ask questions¶

"Is this ADIF record valid? KI7MT2026092820mSSB"

"What values does the ADIF MODE enumeration allow for digital modes?"

"Parse my log file and show me the first 50 QSOs."

"How far is it from DN13 to JN48, and what heading should I point the beam?"

What the validator checks¶

adif-mcp ships ADIF 3.1.7 as ADIF publishes it: 186 fields, 25 enumerations and 28 data types. validate_adif_record checks each field against its ADIF data type and, for enumerated fields, against the enumeration:

Enumeration values match regardless of case, so LoTW's BAND=15M is accepted as 15m.
Import-only values (42 of the Mode enumeration's 91 entries, for example) give a warning, not an error: ADIF allows them on import but not in new records.
Compound values such as CREDIT_SUBMITTED (a list of Credit or Credit:Medium entries) are checked entry by entry.
SUBMODE must be a valid Submode; one that belongs to a different MODE gives a warning. FT4, for example, is MODE=MFSK with SUBMODE=FT4.
Structured types are checked against the grammar ADIF states for them: grid squares (2, 4, 6 or 8 characters, any case) and their extensions and lists (VUCC needs two or four, each four or six characters), Location (XDDD MM.MMM), Boolean (Y or N), and IOTA, WWFF, POTA and SOTA references. What the grammar allows but cannot be right, such as a latitude over 90 degrees or N/S on a longitude, is a warning, never an error.

The server also publishes the MCP resource adif://system/version: the service version and the ADIF specification version it serves.

MCP Inspector¶

adif-mcp --transport streamable-http --port 8003

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

Development¶

git clone https://github.com/qso-graph/adif-mcp.git
cd adif-mcp
uv sync --group dev
uv run pytest

License¶

adif-mcp's own code is GPL-3.0-or-later. See LICENSE for details.

The ADIF specification files are not ours. The package includes ADIF's published files for two versions, the previous and the current (3.1.6 and 3.1.7 today), unmodified: every file in ADIF's resource zip except its test material, in every format ADIF publishes (JSON, XML with all.xml and the XSD, CSV, TSV, XLSX, ODS), with a MANIFEST.json of their SHA-256s per version, from the ADIF Developers Group. They are ADIF's work, and our licence doesn't cover them. The only files in that folder that are ours are the derived Country enumeration and each version's MANIFEST.json. See NOTICE.

Tool Reference¶

Generated from the released server's own tool definitions.

calculate_distance¶

Calculates distance (km) between Maidenhead locators.

Parameter	Type	Required	Default	Description
`start`	string	Yes
`end`	string	Yes

calculate_heading¶

Calculates heading (azimuth) between Maidenhead locators.

Parameter	Type	Required	Default	Description
`start`	string	Yes
`end`	string	Yes

get_version_info¶

Returns the version of the ADIF-MCP server and spec.

No parameters.

list_enumerations¶

Lists the 26 enumerations: ADIF 3.1.7's 25 plus Country (derived).

Each entry's source says whether it is ADIF's own export or derived by adif-mcp, so a consumer loading reference tables can tell them apart.

No parameters.

parse_adif¶

Streaming parser for large ADIF files with record seeking.

SECURITY NOTE: This tool reads files from the local filesystem using the provided path. Only pass paths to ADIF log files you own.

Parameter	Type	Required	Default
`file_path`	string	Yes
`start_at`	integer	No	`1`
`limit`	integer	No	`20`

read_specification_resource¶

Reads an ADIF 3.1.7 specification resource (e.g., 'mode', 'fields', 'all').

An unknown or unreadable name is a tool execution error, so the model can see it failed and correct the name rather than being handed an error document that looks like a successful result.

Parameter	Type	Required	Default	Description
`resource_name`	string	Yes

search_enumerations¶

Searches ADIF 3.1.7 enumerations. Optionally filter by enumeration name.

Parameter	Type	Required	Default	Description
`search_term`	string	Yes
`enumeration`	string	No	`null`

validate_adif_record¶

Validates an ADIF record against 3.1.7 rules including enum membership.

Parameter	Type	Required	Default	Description
`adif_string`	string	Yes