Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@io.github.qso-graph/cq-zones-mcp Which CQ zone is Quebec in?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Source: CQ's WAZ Zone Definitions ("Updated and correct as of April 1, 2018"), © CQ Communications, Inc. and the World Wide Radio Operators Foundation (WWROF). The 40 CQ zones are CQ's: this package serves facts from CQ's list, each citing the zone it comes from, and links to CQ's page rather than copying it. Our GPL-3.0 licence covers our code, not CQ's data.
Checked against: AD1C's country files (Jim Reisert, AD1C), ADIF 3.1.7's subdivision zones, and ARRL's DXCC list. The tests fetch AD1C's and ARRL's files from their sites to validate the facts; neither is included here. where they differ, the owner's list wins (see docs/TRANSCRIPTION.md).
MCP server for CQ zones as CQ publishes them: the 40 zones of CQ's WAZ Zone Definitions (2018-04-01), the zones used by CQ's Worked All Zones award and the CQ World Wide DX Contest. Each zone's entities and subdivisions are given in ADIF's own DXCC and subdivision codes, with CQ's own wording where it splits an area.
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.
uvx cq-zones-mcp # run it; nothing to installRelated MCP server: qrz-mcp
Tool | Description | Key Parameters |
| One zone: its name and every entity, subdivision and boundary CQ lists, with the citation | code |
| Which zones cover an ADIF DXCC entity, or one of its subdivisions | dxcc, subdivision |
| Find zones by name, prefix or wording | text, limit |
| Whether a zone was valid on a date (CQ zones have no validity window) | code, on_date |
| Owner, edition, terms, and the owner's file's URL and SHA-256 | — |
| Service version + the owner's edition served (fleet identity attestation) | — |
No credentials needed — just install and configure your MCP client.
cq-zones-mcp works with any MCP-compatible client. Add the server config and restart — tools appear automatically.
Add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):
{
"mcpServers": {
"cq-zones": {
"command": "uvx",
"args": ["cq-zones-mcp"]
}
}
}Add to .claude/settings.json:
{
"mcpServers": {
"cq-zones": {
"command": "uvx",
"args": ["cq-zones-mcp"]
}
}
}{
"mcpServers": {
"cq-zones": {
"command": "uvx",
"args": ["cq-zones-mcp"]
}
}
}Add to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):
{
"mcpServers": {
"cq-zones": {
"command": "uvx",
"args": ["cq-zones-mcp"]
}
}
}Add to .vscode/mcp.json in your workspace:
{
"servers": {
"cq-zones": {
"command": "uvx",
"args": ["cq-zones-mcp"]
}
}
}Add to ~/.gemini/settings.json (global) or .gemini/settings.json (project):
{
"mcpServers": {
"cq-zones": {
"command": "uvx",
"args": ["cq-zones-mcp"]
}
}
}"Which CQ zone is Quebec in?"
"What does CQ zone 23 cover?"
"Which CQ zones does Canada span?"
cq-zones-mcp --transport streamable-http --port 8016Then open the MCP Inspector at http://localhost:8016.
git clone https://github.com/qso-graph/cq-zones-mcp.git
cd cq-zones-mcp
uv sync --group dev
uv run pytestscripts/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).
cq-zones-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.
Which CQ zones cover an ADIF DXCC entity, or one of its subdivisions.
Where CQ splits an entity (VE2 Quebec at the 50th parallel), each zone is returned with CQ's boundary wording.
| Name | Required | Description | Default |
|---|---|---|---|
| dxcc | Yes | ADIF DXCC entity code (e.g. 291 for the United States, 1 for Canada). | |
| subdivision | No | ADIF Primary_Administrative_Subdivision code, e.g. "QC" or "AZ". |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a read-only, idempotent, non-destructive operation, so safety behavior is covered. The description adds useful context beyond annotations by explaining that split entities can return multiple zones with CQ's boundary wording, though it does not cover not-found or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences and front-loads the core purpose. The second sentence earns its place by documenting the important split-entity return behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter, read-only lookup with full schema coverage, annotations, and an output schema, the description is largely complete for correct invocation. The main remaining gap is routing guidance relative to the sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains both dxcc and subdivision parameters. The description reinforces the entity/subdivision concept but does not add syntax, constraints, or examples beyond what the schema provides, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb-and-resource query: which CQ zones cover an ADIF DXCC entity or subdivision. It is understandable without opening the schema, but it does not explicitly distinguish this from siblings such as cq_zones_lookup, cq_zones_search, or cq_zones_valid_on.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the query wording: an agent can infer this is for mapping a DXCC entity or subdivision to CQ zones. However, the description gives no explicit when-to-use guidance, no exclusions, and no named alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One CQ zone: its name and every entity, subdivision and boundary CQ lists for it, with ADIF codes and the citation.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | A CQ zone number, 1 to 40. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the structural annotations (readOnlyHint: true) by providing rich behavioral context regarding the *output* data: what specific components (entity lists, boundaries, ADIF codes, citation) are provided, which informs the agent about the depth of the lookup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is highly efficient; a single, clear sentence captures the resource, the scope, and the specific data points returned without any extraneous language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the input schema and safety annotations are comprehensive, the description is complete by focusing on the unique value of the lookup—the inclusion of detailed information like boundaries and ADIF codes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 100%, the schema already details the 'code' parameter. The description provides context that confirms the input is a 'CQ zone number, 1 to 40,' meeting the baseline score for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is highly specific, stating that it retrieves a single CQ zone's details, including its name and a list of its entities, subdivisions, and boundaries with ADIF codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While it doesn't explicitly state alternatives, the description clearly defines its function as a granular lookup for a single zone, implicitly distinguishing it from broader search or code-listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find codes whose name, prefixes, area wording or attributes contain every word of text.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Words to look for, e.g. "Quebec", "VE2" or "Antarctic". | |
| limit | No | Most records to return (1 to 200, default 50). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds one genuine behavioral detail — all words must match (conjunctive matching) across multiple fields — but says nothing about result ordering, truncation behavior, or empty-result handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. The matching semantics arrive before any caveats, and every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-shape explanation is correctly omitted, and the AND-matching rule plus searched-field list cover the core invocation decision. The only gap is what happens when matches are numerous — ordering or truncation hints — which is minor given limit is schema-documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with 'text' and 'limit' both documented including bounds and default, so the baseline is 3. The description contributes the extra semantic of which fields 'text' is matched against, but adds nothing for 'limit' beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (find) and resource (codes) and pins down the matching scope: name, prefixes, area wording and attributes. That is more precise than 'search zones', but it never names or contrasts itself with siblings like cq_zones_lookup or cq_zones_codes_for, leaving the agent to infer the search-vs-lookup boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Use is only implied by the verb 'Find'; there is no explicit when-to-use or when-not-to-use guidance and no routing to the alternative tools in the sibling list. The 'every word' clause does at least signal AND-style querying rather than exact-code retrieval, which nudges it above a bare 2.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who owns this list, which edition is served, its terms, and the owner's files' URLs and SHA-256s.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides rich behavioral context by listing the highly specific technical data points it returns, such as 'owner's files' URLs and SHA-256s. This goes beyond simple read/write status provided by the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is highly concise, delivering all necessary context in a single, direct sentence without unnecessary filler or jargon.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are zero input parameters, the description is highly complete, as it informs the agent exactly what specific knowledge is returned upon invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since the tool has zero parameters and 100% schema coverage, the description provides no functional value over the structured data. The baseline score of 3 is appropriate for metadata-only descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the function as retrieving specific metadata (ownership, edition, terms, URLs, and SHA-256s). While it doesn't distinguish its purpose relative to all siblings, it clearly specifies the nature of the 'source info' provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus similar tools like cq_zones_lookup or cq_zones_search. It relies entirely on the agent inferring the correct use case based on the description's content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whether a CQ zone was valid on a date.
CQ's list gives no validity window, so every zone it lists is valid; the tool exists so every owner-list server answers the same questions.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | A CQ zone number, 1 to 40. | |
| on_date | Yes | The date, YYYY-MM-DD. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description adds the important behavioral fact that CQ publishes no validity window, so the answer is effectively always true for listed zones. That is real context an agent cannot get from the schema, though it omits what happens for an out-of-range code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core answer front-loaded. The second sentence is slightly discursive but earns its place by explaining the no-validity-window rationale.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists and parameters are fully described, so the description only needs to convey the tool's semantics and the quirk of constant validity, which it does. Little is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters (code 1-40, date YYYY-MM-DD) are fully documented in the schema. The description only restates 'zone' and 'date' without adding format or edge-case meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific predicate: whether a CQ zone (identified by code) was valid on a given date. It is clearly distinct from lookup/search/codes_for siblings, though it never names them to sharpen the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains why the tool exists (uniform semantics across owner-list servers) but never says when to call it versus cq_zones_lookup, cq_zones_codes_for, or cq_zones_search. Usage is implied rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get cq-zones-mcp's version and the edition of CQ's list it serves.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real information beyond that by stating the tool returns both the package version and the served data edition, which an agent cannot infer from annotations or the empty schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler, front-loading the core action and then the two outputs. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description needn't explain return value structure, and for a zero-parameter read tool it is nearly complete. The only gap is not clarifying how it differs from cq_zones_source_info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description misleads about inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and two distinct pieces of data returned: the package version and the edition of CQ's list being served. That clearly separates it from lookup/search/valid_on siblings, though it doesn't distinguish it from the similarly-named cq_zones_source_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this rather than a sibling, and no mention of prerequisites. The closest overlap, cq_zones_source_info, is never mentioned, leaving the agent to infer the difference from names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0cq_zones_codes_forcq_zones_lookupcq_zones_searchcq_zones_source_infocq_zones_valid_onget_version_infoScored across 6 tools
Lookup, search, codes_for, and valid_on are clearly distinct operations targeting different queries. The only mild overlap is between get_version_info and cq_zones_source_info, since both return server/list metadata, though their descriptions distinguish version from ownership/terms.
Five of six tools use a consistent cq_zones_ prefix with a verb/noun tail (lookup, search, codes_for, valid_on, source_info). get_version_info breaks the pattern by using a bare get_ verb and no cq_zones_ prefix, a minor but visible deviation.
Six tools is well-scoped for a focused reference-data server. Each tool serves a distinct query need without excess, comfortably within the ideal 3-15 range.
The domain is a static CQ zone reference list, so mutation tools are unnecessary. Lookup by zone, search by text, reverse lookup by entity/subdivision, date validity, and source/version metadata cover the read surface fully with no dead ends.
Ziplore: US ZIP to county, FIPS, time zone, Census demographics; radius and city ZIPs. Free, no key.
Ziplore: US ZIP to county, FIPS, time zone, Census demographics; radius and city ZIPs. Free, no key.
Ziplore: US ZIP to county, FIPS, time zone, Census demographics; radius and city ZIPs. Free, no key.
Free, keyless postal/ZIP code lookup: place name(s), state/region, and coordinates.