DX Cluster MCP Server

A FastMCP-based Model Context Protocol (MCP) server for Ham Radio DX Cluster operations. This server enables Claude Desktop and other MCP clients to interact with DX Clusters for reading spots, posting spots, and analyzing propagation data.

Features

• Read DX Spots: Retrieve recent DX spots with optional filtering by band or callsign

• Post DX Spots: Submit new DX spots to the cluster

• Analyze Spots: Perform statistical analysis on spots (band activity, country distribution, mode analysis)

• Connection Management: Check and manage DX Cluster connection status

• SSE Transport: Server-Sent Events transport for remote access

• API Key Authentication: Secure API key-based authentication

• Docker Support: Easy deployment with Docker and docker-compose

Architecture

Prerequisites

• Docker and Docker Compose

• Valid Ham Radio Callsign

• Network access to a DX Cluster (default: dxc.nc7j.com:7373)

• Claude Desktop (for Windows client)

• MCP Proxy (for remote connections)

Installation

1. Clone the Repository

2. Configure Environment

Copy the example environment file and edit it with your settings:

Edit .env with your configuration:

Important: Change the API_KEY to a secure random string!

3. Create External Network

The server uses an external Docker network called ea1rfi-network. Create it before running docker-compose:

4. Start the Server

Check the logs:

The server will be available at http://localhost:8000 (or your server's IP address).

Configuration for Claude Desktop (Windows)

Option 1: Using MCP Proxy (Recommended for Remote Access)

1. Install MCP Proxy on your Windows machine

2. Configure MCP Proxy to connect to your server:

Create or edit the MCP Proxy configuration file with the server URL and API key:

3. Configure Claude Desktop to use MCP Proxy

Edit Claude Desktop configuration file (typically at %APPDATA%\Claude\claude_desktop_config.json):

Option 2: Direct SSE Connection (if supported)

If your MCP client supports direct SSE connections, configure it like this:

Available Tools

1. read_spots

Read recent DX spots from the cluster.

Parameters:

• count (int, optional): Number of spots to retrieve (default: 10, max: 100)

• band (string, optional): Band filter (e.g., "20m", "40m", "15m")

• callsign (string, optional): Callsign filter to search for specific station

Example:

2. post_spot

Post a DX spot to the cluster.

Parameters:

• frequency (float): Frequency in MHz (e.g., 14.074 for 20m FT8)

• dx_callsign (string): Callsign of the station being spotted

• comment (string, optional): Comment about the spot (mode, signal report, etc.)

Example:

3. analyze_spots

Analyze DX spots to provide insights and statistics.

Parameters:

• hours (int, optional): Number of hours to analyze (default: 1, max: 24)

• analysis_type (string): Type of analysis

  • "summary": Overall statistics

  • "bands": Spots per band distribution

  • "countries": Spots per country prefix

  • "modes": Spots per operating mode

Example:

4. check_connection

Check the connection status to the DX Cluster.

Parameters: None

Returns connection status, cluster info, and configuration.

Usage Examples

Once configured, you can interact with the DX Cluster through Claude Desktop:

Example prompts:

• "Show me the last 20 DX spots on 20 meters"

• "Post a spot for EA1RFI on 14.074 MHz with FT8"

• "Analyze the band activity for the last 3 hours"

• "What countries have been spotted in the last hour?"

• "Check if we're connected to the DX cluster"

Troubleshooting

Connection Issues

1. Check server logs:

   docker-compose logs -f

2. Verify network connectivity:

   docker exec dx-cluster-mcp-server ping dxc.nc7j.com

3. Test telnet connection to cluster:

   telnet dxc.nc7j.com 7373

Authentication Errors

• Verify the API key matches between .env file and Claude Desktop configuration

• Check that the Authorization header is formatted correctly: Bearer <your-api-key>

Docker Network Issues

• Ensure the external network exists:

  docker network ls | grep ea1rfi-network

• Recreate the network if needed:

  docker network rm ea1rfi-network docker network create ea1rfi-network

Development

Local Testing

For local development without Docker:

1. Install dependencies:

   pip install -r requirements.txt

2. Set environment variables:

   export CALLSIGN=N0CALL export DX_CLUSTER_HOST=dxc.nc7j.com export DX_CLUSTER_PORT=7373 export API_KEY=test-key

3. Run the server:

   python server.py

Testing Tools

You can test the MCP tools using the FastMCP CLI or MCP Inspector:

Security Considerations

• API Key: Always use a strong, randomly generated API key in production

• Network Security: Consider using HTTPS with a reverse proxy (nginx, traefik)

• Firewall: Restrict access to port 8000 to trusted IP addresses

• Callsign: Ensure you use your own licensed callsign

• Cluster Rules: Follow the rules and etiquette of the DX Cluster you're connecting to

DX Cluster Resources

This server is compatible with standard DX Cluster software including:

• DXSpider

• AR-Cluster

• CC Cluster

Popular public DX Clusters:

• NC7J: dxc.nc7j.com:7373

• HamQTH: hamqth.com:7300

• W6CUA: w6cua.no-ip.org:7373

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

References

• FastMCP Documentation

• Model Context Protocol

• DX Cluster Resources

• AR-Cluster User Manual

Support

For issues and questions, please open an issue on GitHub.

73 de EA1RFI