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

┌─────────────────────┐
│  Claude Desktop     │
│    (Windows)        │
└──────────┬──────────┘
           │ MCP Protocol (SSE + API Key)
           │
    ┌──────▼──────────┐
    │   MCP Proxy     │
    │   (Windows)     │
    └──────┬──────────┘
           │ HTTP/SSE
           │
    ┌──────▼──────────┐
    │  DX Cluster     │
    │  MCP Server     │
    │   (Docker)      │
    └──────┬──────────┘
           │ Telnet
           │
    ┌──────▼──────────┐
    │  DX Cluster     │
    │  (e.g. NC7J)    │
    └─────────────────┘

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

git clone <repository-url>
cd dx_cluster_mcp

2. Configure Environment

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

cp .env.example .env

Edit .env with your configuration:

# Your ham radio callsign (required)
CALLSIGN=EA1RFI

# DX Cluster connection (default is NC7J)
DX_CLUSTER_HOST=dxc.nc7j.com
DX_CLUSTER_PORT=7373

# API Key for authentication (generate a secure random string)
API_KEY=your-very-secure-random-api-key-here-change-me

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:

docker network create ea1rfi-network

4. Start the Server

docker-compose up -d

Check the logs:

docker-compose logs -f

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:

{
  "dx-cluster": {
    "url": "http://your-server-ip:8000/sse",
    "headers": {
      "Authorization": "Bearer your-very-secure-random-api-key-here-change-me"
    }
  }
}

3. Configure Claude Desktop to use MCP Proxy

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

{
  "mcpServers": {
    "dx-cluster": {
      "command": "mcp-proxy",
      "args": ["dx-cluster"]
    }
  }
}

Option 2: Direct SSE Connection (if supported)

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

{
  "mcpServers": {
    "dx-cluster": {
      "url": "http://your-server-ip:8000/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer your-very-secure-random-api-key-here-change-me"
      }
    }
  }
}

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:

{
  "count": 20,
  "band": "20m"
}

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:

{
  "frequency": 14.074,
  "dx_callsign": "EA1RFI",
  "comment": "FT8 +10dB"
}

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:

{
  "hours": 2,
  "analysis_type": "bands"
}

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:

# Using FastMCP CLI
fastmcp dev server.py

# Or test with curl (SSE endpoint)
curl -H "Authorization: Bearer your-api-key" \
     http://localhost:8000/sse

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