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? CALL:5KI7MT<QSO_DATE:8>20260928BAND:320mMODE:3SSB"

"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.

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

Compliance & Provenance

adif-mcp follows the ADIF Specification (currently 3.1.7) and uses registered Program IDs to identify all exports:

ADIF-MCP -- Core engine
ADIF-MCP-LOTW -- LoTW server
ADIF-MCP-EQSL -- eQSL server
ADIF-MCP-QRZ -- QRZ server

The project uses APP_ fields for provenance when augmenting records:

APP_ADIF-MCP_OP -- operation performed (normalize, validate, merge)
APP_ADIF-MCP-LOTW_ACTION -- LoTW server operation
APP_ADIF-MCP-EQSL_TIME -- timestamp of eQSL merge

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 two small catalog files. See NOTICE.

Metadata

Release files for adif-mcp 1.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for adif-mcp 1.2.2
File	Size	Uploaded
adif_mcp-1.2.2.tar.gz	2.5 MB	Oct 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for adif-mcp 1.2.2
File	Interpreter	ABI	Platform	Reset
adif_mcp-1.2.2-py3-none-any.whl 2.9 MB Oct 11, 2026	Python 3	none	any	Details

Total release size: 5.4 MB

Release files / adif_mcp-1.2.2.tar.gz

Download URL	adif_mcp-1.2.2.tar.gz
Size	2.5 MB
Tags	Source
SHA-256 checksum How to use checksums	`3c7aba9ef6a73190ffefbc7145f73197343542354ed9924686a98638da392b15`
BLAKE2b-256 checksum How to use checksums	`0a5083c38bfb2aed80b74ed0b4e016a7cfa775b3461b990e4380c26faa04268e`
Upload date	Oct 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/qso-graph/adif-mcp
Publishing commit: github.com/qso-graph/adif-mcp/tree/1dc77dddadf63e2164445c4e8dd12c24621db4eb

Workflow

Publishing configuration: github.com/qso-graph/adif-mcp/blob/1dc77dddadf63e2164445c4e8dd12c24621db4eb/.github/workflows/publish.yml
Publishing logs: github.com/qso-graph/adif-mcp/actions/runs/38103021185/attempts/1

Artifact

Subject: adif_mcp-1.2.2.tar.gz
SHA-256 checksum: 3c7aba9ef6a73190ffefbc7145f73197343542354ed9924686a98638da392b15 Verifying attestations

Release files / adif_mcp-1.2.2-py3-none-any.whl

Download URL	adif_mcp-1.2.2-py3-none-any.whl
Size	2.9 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`01ee2ff4b9512924e7ee14815f7dca43bcb1168a9764a91a8169f81ee18ec9b8`
BLAKE2b-256 checksum How to use checksums	`aa7e0bd7d40f47bcb5abacec0b257dcc186ff317f2ae9d7568c759b3f2f1f9b3`
Upload date	Oct 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/qso-graph/adif-mcp
Publishing commit: github.com/qso-graph/adif-mcp/tree/1dc77dddadf63e2164445c4e8dd12c24621db4eb

Workflow

Publishing configuration: github.com/qso-graph/adif-mcp/blob/1dc77dddadf63e2164445c4e8dd12c24621db4eb/.github/workflows/publish.yml
Publishing logs: github.com/qso-graph/adif-mcp/actions/runs/38103021185/attempts/1

Artifact

Subject: adif_mcp-1.2.2-py3-none-any.whl
SHA-256 checksum: 01ee2ff4b9512924e7ee14815f7dca43bcb1168a9764a91a8169f81ee18ec9b8 Verifying attestations