adif-mcp

Core Model Context Protocol (MCP) server for Amateur Radio Logging, built on the ADIF 3.1.6 specification.

Overview

adif-mcp gives AI agents safe, typed access to Amateur Radio logging data. It validates and parses ADIF records, searches the full ADIF 3.1.6 specification (fields, enumerations, data types), and provides geospatial utilities for Maidenhead locators. It also provides persona management and keyring-backed credential storage used by the qso-graph family of MCP servers.

Quick Start

pip install adif-mcp

Configure Your MCP Client

adif-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": {
    "adif": {
      "command": "adif-mcp"
    }
  }
}

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "adif": {
      "command": "adif-mcp"
    }
  }
}

ChatGPT Desktop

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

{
  "mcpServers": {
    "adif": {
      "command": "adif-mcp"
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "adif": {
      "command": "adif-mcp"
    }
  }
}

VS Code / GitHub Copilot

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

{
  "servers": {
    "adif": {
      "command": "adif-mcp"
    }
  }
}

Gemini CLI

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

{
  "mcpServers": {
    "adif": {
      "command": "adif-mcp"
    }
  }
}

Tools

adif-mcp exposes 8 tools via the Model Context Protocol:

Category	Tool	Description
Validation	validate_adif_record	Validate a raw ADIF string against the 3.1.6 spec
Validation	parse_adif	Streaming parser for large ADIF files with pagination
Spec	read_specification_resource	Retrieve raw JSON for any spec module (band, mode, fields)
Spec	list_enumerations	List all ADIF enumerations with entry counts
Spec	search_enumerations	Search enumeration records by keyword
Geospatial	calculate_distance	Great Circle distance (km) between two Maidenhead locators
Geospatial	calculate_heading	Initial beam heading (azimuth) between two locators
System	get_version_info	Active service version and ADIF spec version

Architecture

adif-mcp is the foundation package -- ADIF spec tools, persona management, and credential storage. Service integrations are separate MCP servers that depend on adif-mcp for identity and auth:

Package	PyPI	What It Does
adif-mcp	v0.9.6	ADIF 3.1.6 spec tools + persona/credential management
lotw-mcp	v0.2.0	LoTW confirmations, QSOs, DXCC credits, user activity
eqsl-mcp	v0.2.0	eQSL inbox, verification, AG status, last upload
qrz-mcp	v0.2.1	Callsign lookup, DXCC, logbook status/fetch
hamqth-mcp	v0.2.0	Callsign lookup, DXCC, bio, activity, DX spots, RBN
pota-mcp	v0.1.1	Parks on the Air spots, park info, stats, schedules
sota-mcp	v0.1.1	Summits on the Air spots, alerts, summit info, stats
solar-mcp	v0.1.1	Space weather conditions, forecasts, band outlook
wspr-mcp	v0.1.1	WSPR beacon spots, propagation, band activity
iota-mcp	v0.1.0	Islands on the Air lookup, search, nearby groups

Authenticated servers use adif-mcp for persona lookup and keyring-backed credentials. Operators install only the servers they need. Each server is independently versioned with no unnecessary dependencies.

Compliance & Provenance

adif-mcp follows the ADIF Specification (currently 3.1.6) 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

License

GPL-3.0-or-later. See LICENSE for details.