darc-dok-mcp¶

Source: the Deutscher Amateur-Radio-Club e.V. (DARC): the DOK-Liste (DARC DX-Referat, by Karsten Radwan, DL2ABM, 26.12.2016) and the special-DOK list (DARC SDOK-Referat). DOKs are DARC's: this package serves the lists' rows as facts, each citing its page or row, and links to DARC's files rather than copying them. Our GPL-3.0 licence covers our code, not DARC's data.

MCP server for DARC DOKs and special DOKs as DARC publishes them: the local-club codes of DARC's DOK-Liste (2016-12-26) and the event codes of DARC's special-DOK list, with each special DOK's validity window. DOKs are used for DARC's DLD award, the DOK best-lists and the WAG contest, and in ADIF's DARC_DOK field.

Part of the qso-graph project. No network, no authentication: the facts from the owner's list ship with the package, and every answer names its source.

Install¶

uvx darc-dok-mcp            # run it; nothing to install

Tools¶

Tool	Description	Key Parameters
`darc_dok_lookup`	One DOK or special DOK: district and club, or purpose, callsign, window and sponsoring club	code
`darc_dok_valid_on`	Whether a DOK or special DOK was valid on a QSO's date	code, on_date
`darc_dok_search`	Find DOKs by club, town, district or purpose	text, limit
`darc_dok_codes_for`	Kept for the shared tool set; DOKs map to no ADIF subdivision	dxcc, subdivision
`darc_dok_source_info`	Owner, editions, terms, and the owner's files' URLs and SHA-256s	—
`get_version_info`	Service version + the owner's edition served (fleet identity attestation)	—

Quick Start¶

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

Configure your MCP client¶

darc-dok-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": {
    "darc-dok": {
      "command": "uvx",
      "args": ["darc-dok-mcp"]
    }
  }
}

Claude Code¶

Add to .claude/settings.json:

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

ChatGPT Desktop¶

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

Cursor¶

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

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

VS Code / GitHub Copilot¶

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

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

Gemini CLI¶

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

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

Ask questions¶

"Which club is DOK A01?"

"Was special DOK 01ALT valid on 2004-06-01?"

"Which DOKs are in district Baden?"

MCP Inspector¶

darc-dok-mcp --transport streamable-http --port 8018

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

Development¶

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

scripts/fetch_published.py fetches the owner's document(s) into published/ (not committed) and checks their SHA-256s; uv run pytest --live runs the tests that need them. scripts/build.py regenerates derived/ and load.sql, a PostgreSQL load for QSO Graph's reference data (load QG ADIF's adif schema first).

License¶

darc-dok-mcp's own code is GPL-3.0-or-later. See LICENSE. The data it serves is the owner's, credited at the top of this page: our licence doesn't cover it, and we claim no rights in it. The owner's document itself is not included; data/SOURCE.json records its URL and SHA-256 so anyone can check the facts against it. Files we built from the facts (data/derived/) are ours and labelled as ours. How the owner's text was read is recorded in docs/TRANSCRIPTION.md. See NOTICE.

Tool Reference¶

Generated from the released server's own tool definitions.

darc_dok_codes_for¶

DOK lists don't map to ADIF subdivisions: this answers for entity 230 (Germany) with nothing per subdivision. Use darc_dok_search for a district or town.

Parameter	Type	Required	Default	Description
`dxcc`	integer	Yes		ADIF DXCC entity code (e.g. 291 for the United States, 1 for Canada).
`subdivision`	string	No	`null`	ADIF Primary_Administrative_Subdivision code, e.g. "QC" or "AZ".

darc_dok_lookup¶

One DOK or special DOK: the district and local club (DOKs), or the purpose, callsign, validity window and sponsoring club (special DOKs), with the citation.

Parameter	Type	Required	Default	Description
`code`	string	Yes		A DOK (e.g. A01) or special DOK (e.g. 1000ER).

darc_dok_search¶

Find codes whose name, prefixes, area wording or attributes contain every word of text.

Parameter	Type	Required	Default	Description
`text`	string	Yes		Words to look for, e.g. "Konstanz", "Baden" or "Jubiläum".
`limit`	integer	No	`50`	Most records to return (1 to 200, default 50).

darc_dok_source_info¶

Who owns this list, which edition is served, its terms, and the owner's files' URLs and SHA-256s.

No parameters.

darc_dok_valid_on¶

Whether a DOK or special DOK was valid on a date: a special DOK counts only inside the window DARC published for it. A DOK merged into another (e.g. A49, merged into A12 in 2001) shows replaced_by.

Parameter	Type	Required	Default	Description
`code`	string	Yes		A DOK (e.g. A01) or special DOK (e.g. 1000ER).
`on_date`	string	Yes		The date, YYYY-MM-DD.

get_version_info¶

Get darc-dok-mcp's version and the edition of DARC's list it serves.

Returns: service_name, service_version (PyPI), and spec_version (the owner's edition).

No parameters.