DX Cluster MCP Server

A FastMCP-based Model Context Protocol (MCP) server for Ham Radio DX Cluster integration with Auth0 authentication. Connect to DX Cluster networks from Claude Desktop to read spots, create spots, and perform comprehensive propagation analysis.

Features

• DX Cluster Integration: Connect to any DXSpider, AR-Cluster, or CC Cluster server via telnet

• OAuth Authentication: Secure access using Auth0 (configurable)

• Comprehensive Tools:

  • Read recent DX spots with detailed information

  • Post new DX spots to the cluster

  • Analyze band activity and propagation trends

  • Track DX entity statistics

  • Identify rare DX opportunities

  • Time-based propagation analysis

Quick Start

Prerequisites

• Docker and Docker Compose

• Amateur radio callsign

• Auth0 account (for authentication) - see setup instructions below

1. Clone and Configure

2. Configure Environment Variables

Edit .env file:

3. Deploy with Docker Compose

The server will be available at http://localhost:8000.

Auth0 Setup Instructions

Follow these steps to set up Auth0 authentication:

Step 1: Create Auth0 Account

1. Go to Auth0 and sign up for a free account

2. Create a new tenant (e.g., "my-ham-radio-apps")

Step 2: Create an Application

1. In Auth0 Dashboard, go to Applications → Applications

2. Click Create Application

3. Name: "DX Cluster MCP Server"

4. Application Type: Machine to Machine Applications

5. Click Create

Step 3: Configure Application Settings

1. In your application settings, note down:

   • Domain (e.g., your-domain.auth0.com)

   • Client ID

   • Client Secret

2. Scroll to Application URIs:

   • Allowed Callback URLs: http://localhost:8000/auth/callback

   • Allowed Logout URLs: http://localhost:8000

   • Allowed Web Origins: http://localhost:8000

3. Click Save Changes

Step 4: Configure API (Optional but Recommended)

1. Go to Applications → APIs

2. Click Create API

3. Name: "DX Cluster MCP API"

4. Identifier: https://dx-cluster-mcp-api

5. Click Create

Step 5: Update Environment Variables

Update your .env file with the Auth0 credentials:

Step 6: Production Deployment (Optional)

For production deployment with a public domain:

1. Update Allowed Callback URLs to include your domain:

   https://your-domain.com/auth/callback

2. Update .env:

   SERVER_BASE_URL=https://your-domain.com AUTH0_CALLBACK_URL=https://your-domain.com/auth/callback

Claude Desktop Configuration

To use this MCP server with Claude Desktop on Windows:

Option 1: Remote Connection (Recommended)

1. Ensure the server is running and accessible from your Windows machine

2. Add to Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json):

Option 2: Local WSL2

If running in WSL2 on Windows:

After updating the configuration, restart Claude Desktop.

Available Tools

1. read_spots

Read recent DX spots from the cluster.

Parameters:

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

Example:

2. create_spot

Post a new DX spot to the cluster.

Parameters:

• dx_callsign (str): Callsign of the DX station

• frequency (float): Frequency in kHz

• comment (str, optional): Comment about the spot

Example:

3. analyze_spots

Perform comprehensive analysis of recent spots.

Parameters:

• spot_count (int, optional): Number of spots to analyze (10-200, default: 50)

• include_rare_dx (bool, optional): Include rare DX alerts (default: true)

Example:

Returns:

• Summary statistics

• Band activity breakdown

• Top DX entities

• Hourly propagation trends

• Rare DX alerts

4. get_band_activity

Get current band activity statistics.

Parameters:

• spot_count (int, optional): Number of spots to analyze (default: 50)

Example:

5. cluster_info

Get information about the cluster connection.

Example:

Usage Examples

Once connected through Claude Desktop:

Development

Running Locally Without Docker

Running Without Authentication (Development)

For development/testing, you can run without Auth0:

1. Comment out or remove Auth0 environment variables in .env

2. The server will start in unauthenticated mode (not recommended for production)

Popular DX Cluster Servers

Here are some popular DX Cluster servers you can connect to:

Note: Some clusters may require registration. Check with the cluster operator.

Troubleshooting

Connection Issues

Common Issues

1. "Failed to connect to DX Cluster"

   • Verify DX_CLUSTER_HOST and DX_CLUSTER_PORT are correct

   • Some clusters may be down or require registration

   • Check firewall settings

2. Authentication Errors

   • Verify Auth0 credentials in .env

   • Check callback URLs in Auth0 dashboard

   • Ensure SERVER_BASE_URL matches your deployment

3. Invalid Callsign

   • Ensure DX_CLUSTER_CALLSIGN is set correctly

   • Must be a valid amateur radio callsign

Architecture

License

See LICENSE file for details.

Contributing

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

Resources

• FastMCP Documentation

• Model Context Protocol

• DXSpider

• Auth0 Documentation

Support

For issues or questions:

• Open an issue on GitHub

• Check the troubleshooting section above

73 de [Your Callsign] - Happy DXing!