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?
With no annotations, the description carries the full behavioral burden. It adds useful context by explaining that split entities return each zone with boundary wording, but it omits whether the operation is read-only, what happens on invalid input, or any other operational 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?
Two tightly written sentences with zero waste. The purpose is front-loaded, and the second sentence adds specific return behavior without unnecessary elaboration.
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 an output schema exists, the description need not explain return values in detail. It still adds the important nuance about split-entity boundary wording, and the simple two-parameter input is fully covered by the schema. The only missing piece is explicit usage guidance relative to siblings.
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 fully documents the dxcc and subdivision parameters. The description adds no additional parameter meaning beyond what the input schema provides, making the baseline of 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 states a specific verb and resource: which CQ zones cover a given ADIF DXCC entity or subdivision. It clearly distinguishes the tool's output from a generic lookup, but it does not explicitly differentiate itself from sibling tools like cq_zones_lookup or cq_zones_search.
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 explicit guidance on when to use this tool versus alternatives, nor any stated prerequisites or exclusions. The context implies it is a mapping lookup, but an agent receives no routing help.
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?
No annotations are provided, so the description carries the full burden. It discloses the retrieval nature and scope of returned fields, but says nothing about permissions, rate limits, error behavior, or what happens when a code has no matching zone. Adequate but incomplete.
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 efficient sentence with no filler, front-loaded with the resource. Structure is fine, though the dense list of returned fields makes it slightly harder to scan.
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 values, and it correctly conveys the lookup scope and the fields returned. It is nearly complete for a one-parameter read tool, only lacking routing guidance versus siblings.
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%, and the schema already documents the single 'code' parameter with its 1–40 range. The description adds no syntax or format details beyond what the schema supplies, so the baseline of 3 is 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 names a specific resource ('One CQ zone') and enumerates the returned data (name, entities, subdivisions, boundaries, ADIF codes, citation), making the purpose concrete. It doesn't explicitly distinguish itself from cq_zones_search or cq_zones_codes_for, so it stops short of a 5.
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 explicit when-to-use or when-not-to-use guidance. The agent must infer from the description that this is the single-zone detail lookup, and nothing names the alternatives cq_zones_search or cq_zones_codes_for.
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?
No annotations, so the description carries the burden. It discloses the searchable fields and implies AND-matching across 'every word', which is useful behavioral context, but omits ordering/pagination behavior, result format, and whether matching is case-insensitive or prefix-based beyond the field list.
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 tight sentence that front-loads the verb and the search scope. No filler words.
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-value explanation is not required, and annotations are absent. The description covers the core matching behavior but doesn't say how this search differs from lookup-oriented siblings or when an agent should prefer it, leaving a routing gap.
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 both parameters are already documented in the schema (text examples, limit range). The description adds the 'every word' containment semantics for text, but this is the baseline schema-documented case.
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 verb (Find) and resource (codes, implicitly CQ zones codes), with detail on which fields are searched (name, prefixes, area wording, attributes). This distinguishes it from lookup-oriented siblings like cq_zones_lookup and cq_zones_valid_on, though the sibling differentiation is implicit rather than named.
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?
No guidance on when to use this search versus siblings such as cq_zones_lookup or cq_zones_codes_for. The 'every word' matching semantics is implied but not stated, and no conditions for choosing this tool are given.
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?
No annotations are provided, so the description carries the full behavioral burden. It implies a read-only metadata retrieval, but does not state side effects, permissions, rate limits, or whether the SHA-256/URL info might change. It adds very little beyond naming fields. An output schema exists, so return structure is partly covered there, but behavior around the data is not.
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 a single sentence, which is concise, but it is a noun phrase list that is somewhat dense and not front-loaded with a clear purpose verb. It is not wasteful, but the structure is less helpful than a brief 'Retrieve …' statement would be.
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 the tool has no parameters and an output schema, the description is adequate to understand what is returned. However, it lacks any context about when this source info matters relative to the other cq_zones tools, which is important in a family of related tools. It is minimally complete but leaves usage context to inference.
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?
With zero parameters and 100% schema coverage, the baseline is 4. The description correctly implies that no inputs are needed to fetch the source info, matching the empty schema. No additional parameter meaning is required.
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 what information is returned (owner, edition, terms, file URLs and SHA-256s) but does so as a noun-phrase list rather than a clear verb+resource statement. It is distinguishable from siblings like cq_zones_lookup or get_version_info only by inference; the name 'cq_zones_source_info' plus the listed contents suggest metadata about the zone list source. It is specific but not framed as an action.
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?
No guidance on when to use this tool versus alternatives such as get_version_info (which likely covers version/edition) or cq_zones_lookup. There is no when-to-use, when-not-to-use, or explicit sibling differentiation.
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?
With no annotations, the description carries the full behavioral burden, and it discloses a genuinely non-obvious trait: CQ's list has no validity window, so every listed zone is valid. That tells the agent the expected answer before it calls. It stops short of describing unknown/out-of-range code handling or confirming read-only semantics.
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 sentences, front-loaded with the operation before the rationale. The second sentence is somewhat meta but earns its place by explaining the always-valid semantics. No wasted text.
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-value explanation is unnecessary, and the description supplies the key semantic quirk an agent needs. For a simple two-required-param boolean query, it is nearly complete, only missing error/edge-case behavior.
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%: code is documented as 1-40 and on_date as YYYY-MM-DD. The description adds no format or range detail beyond that, so the baseline 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?
The description states a specific operation on a specific resource: whether a CQ zone was valid on a given date. It is clear and self-contained, but it does not explicitly differentiate itself from siblings like cq_zones_lookup or cq_zones_search, so an agent must infer 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?
The rationale 'so every owner-list server answers the same questions' implies the tool is the canonical validity check, but it never states when to prefer this over cq_zones_lookup or cq_zones_search. Usage is implied rather than spelled out.
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.
Returns: service_name, service_version (PyPI), and spec_version (the owner's edition).
| 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?
No annotations are provided, so the description carries the full burden. It discloses the returned fields and that service_version comes from PyPI, which is useful behavioral context, but says nothing about auth requirements, caching, or whether the call has side effects (it is implicitly read-only).
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, front-loaded sentences with no filler. The 'Returns:' block partially duplicates the output schema, but it is brief enough to be harmless.
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 detailed return-value documentation is not strictly required; the description nonetheless names the key fields. For a zero-param metadata tool this is essentially complete, with only usage context missing.
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 per the baseline this scores 4. The description correctly implies no input is needed and focuses entirely on what is returned.
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 verb+resource (get version info) and clarifies it covers both the service version and the served CQ list edition. It is naturally distinguishable from the lookup/search siblings, though it doesn't explicitly contrast itself with them.
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 only implied – an agent can infer this is a metadata/diagnostic call, but the description never states when to reach for it (e.g., before other calls, to verify spec compatibility) or whether any alternative exists.
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
Most tools have clearly distinct purposes: lookup, search, reverse entity lookup, validity check, and source metadata. get_version_info and cq_zones_source_info both provide metadata about the service/list, which could cause slight confusion, but the descriptions differentiate version details from ownership and files.
Five tools use the consistent cq_zones_ prefix, making the domain grouping clear. get_version_info uses a different get_ convention for the service-level metadata, which is a minor deviation but still readable and predictable.
Six tools is well-scoped for a reference-data MCP server. Each tool covers a useful query type without excessive overlap or redundancy.
The read-only surface covers version/source metadata, single-zone lookup, text search, entity-to-zone reverse lookup, and validity checking. A direct list-all-zones operation is absent, but search and lookup likely let agents work around this minor gap.
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.
Postal lookups for 120 countries with cited sources; deep US tier: demographics, climate, area codes