# 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
```bash
# Clone the repository
git clone <repository-url>
cd dx_cluster_mcp
# Copy environment template
cp .env.example .env
# Edit .env with your configuration
nano .env
```
### 2. Configure Environment Variables
Edit `.env` file:
```bash
# DX Cluster Configuration
DX_CLUSTER_HOST=dxspider.net # Your preferred cluster
DX_CLUSTER_PORT=7300 # Cluster port
DX_CLUSTER_CALLSIGN=YOUR_CALLSIGN # Your amateur radio callsign
# Auth0 Configuration (see Auth0 Setup below)
AUTH0_DOMAIN=your-domain.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret
AUTH0_AUDIENCE=https://dx-cluster-mcp-api
AUTH0_CALLBACK_URL=http://localhost:8000/auth/callback
# Server Configuration
SERVER_PORT=8000
SERVER_BASE_URL=http://localhost:8000
```
### 3. Deploy with Docker Compose
```bash
# Build and start the server
docker-compose up -d
# View logs
docker-compose logs -f
# Stop the server
docker-compose down
```
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](https://auth0.com/) 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 (Required)
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:
```bash
AUTH0_DOMAIN=your-domain.auth0.com
AUTH0_CLIENT_ID=your_client_id_from_step3
AUTH0_CLIENT_SECRET=your_client_secret_from_step3
AUTH0_AUDIENCE=https://dx-cluster-mcp-api
AUTH0_CALLBACK_URL=http://localhost:8000/auth/callback
```
**Note:** The `AUTH0_AUDIENCE` must match the API Identifier you created in Step 4.
### 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`:
```bash
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`):
```json
{
"mcpServers": {
"dx-cluster": {
"url": "http://your-server-ip:8000/sse",
"transport": "sse"
}
}
}
```
### Option 2: Local WSL2
If running in WSL2 on Windows:
```json
{
"mcpServers": {
"dx-cluster": {
"url": "http://localhost:8000/sse",
"transport": "sse"
}
}
}
```
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:**
```
Read the last 20 DX spots
```
### 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:**
```
Create a spot for W1AW on 14.025 MHz (14025 kHz) with comment "CQ"
```
### 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:**
```
Analyze the last 100 spots and show me propagation trends
```
**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:**
```
Show me which bands are most active right now
```
### 5. cluster_info
Get information about the cluster connection.
**Example:**
```
Show cluster connection information
```
## Usage Examples
Once connected through Claude Desktop:
```
"Read the last 25 DX spots"
"Which bands are most active right now?"
"Analyze the last 100 spots and tell me about propagation conditions"
"Post a spot for K1TTT on 21.025 MHz (21025 kHz) with comment 'Strong signal'"
"Show me rare DX opportunities from the last 50 spots"
"What are the propagation trends by time of day?"
```
## Development
### Running Locally Without Docker
```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Set environment variables
export DX_CLUSTER_HOST=dxspider.net
export DX_CLUSTER_PORT=7300
export DX_CLUSTER_CALLSIGN=YOUR_CALLSIGN
# ... other env vars
# Run server
python -m src.server
```
### 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:
| Server | Host | Port | Type |
|--------|------|------|------|
| DXSpider | dxspider.net | 7300 | DXSpider |
| NY2PO | ny2po.com | 7300 | DXSpider |
| W6CUA | w6cua.no-ip.org | 7300 | DXSpider |
| VE7CC | ve7cc.net | 23 | CC Cluster |
| K7AR | k7ar.org | 7300 | DXSpider |
**Note:** Some clusters may require registration. Check with the cluster operator.
## Troubleshooting
### Connection Issues
```bash
# Check if server is running
docker-compose ps
# View server logs
docker-compose logs -f dx-cluster-mcp
# Test connectivity
curl http://localhost:8000/health
```
### 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
```
┌─────────────────┐
│ Claude Desktop │
│ (Windows) │
└────────┬────────┘
│ SSE/HTTP
│
┌────────▼────────────────┐
│ FastMCP Server │
│ ┌──────────────────┐ │
│ │ Auth0 OAuth │ │
│ └──────────────────┘ │
│ ┌──────────────────┐ │
│ │ MCP Tools │ │
│ │ - read_spots │ │
│ │ - create_spot │ │
│ │ - analyze_spots │ │
│ └──────────────────┘ │
│ ┌──────────────────┐ │
│ │ DX Cluster │ │
│ │ Client │ │
│ └──────────────────┘ │
└────────┬────────────────┘
│ Telnet
│
┌────────▼────────────────┐
│ DX Cluster Server │
│ (DXSpider/AR-Cluster) │
└─────────────────────────┘
```
## License
See LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
## Resources
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [DXSpider](http://www.dxspider.net/)
- [Auth0 Documentation](https://auth0.com/docs)
## Support
For issues or questions:
- Open an issue on GitHub
- Check the troubleshooting section above
---
**73 de [Your Callsign]** - Happy DXing!
