# Complete Setup Guide for DX Cluster MCP Server
This guide provides step-by-step instructions to get your DX Cluster MCP server up and running with Auth0 authentication and Claude Desktop integration.
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Auth0 Configuration](#auth0-configuration)
3. [Server Setup](#server-setup)
4. [Claude Desktop Integration](#claude-desktop-integration)
5. [Testing](#testing)
6. [Production Deployment](#production-deployment)
## Prerequisites
### Required
- **Docker & Docker Compose**: [Install Docker](https://docs.docker.com/get-docker/)
- **Amateur Radio License**: Valid callsign for cluster access
- **Claude Desktop**: [Download for Windows](https://claude.ai/download)
### Optional
- **Auth0 Account**: For authentication (free tier available)
- **Domain Name**: For production deployment
## Auth0 Configuration
### 1. Create Auth0 Account
1. Navigate to [auth0.com](https://auth0.com/)
2. Click "Sign Up" and create a free account
3. During setup, create a tenant name (e.g., "ham-radio-mcp")
4. Choose your region (closest to your users)
### 2. Create Application
1. Log in to Auth0 Dashboard
2. Navigate to **Applications** → **Applications**
3. Click **Create Application**
4. Configure:
- **Name**: `DX Cluster MCP Server`
- **Application Type**: Select **Regular Web Application**
- Click **Create**
### 3. Configure Application Settings
1. Click on your newly created application
2. Go to the **Settings** tab
3. Note these values (you'll need them later):
```
Domain: your-tenant.auth0.com
Client ID: (copy this)
Client Secret: (copy this - click to reveal)
```
4. Scroll down to **Application URIs** and configure:
```
Allowed Callback URLs:
http://localhost:8000/auth/callback
Allowed Logout URLs:
http://localhost:8000
Allowed Web Origins:
http://localhost:8000
```
5. Scroll to **Advanced Settings** → **Grant Types**
6. Ensure these are checked:
- Authorization Code
- Refresh Token
7. Click **Save Changes**
### 4. Configure Allowed Origins
1. Scroll to **Cross-Origin Authentication**
2. Add `http://localhost:8000` to **Allowed Origins (CORS)**
3. Save changes
### 5. Create API (Required)
1. Go to **Applications** → **APIs**
2. Click **Create API**
3. Configure:
- **Name**: `DX Cluster MCP API`
- **Identifier**: `https://dx-cluster-mcp-api`
- **Signing Algorithm**: `RS256`
4. Click **Create**
## Server Setup
### 1. Clone Repository
```bash
git clone <repository-url>
cd dx_cluster_mcp
```
### 2. Configure Environment
```bash
# Copy the example environment file
cp .env.example .env
# Edit the .env file
nano .env # or use your preferred editor
```
### 3. Edit Environment Variables
Update `.env` with your values:
```bash
# DX Cluster Configuration
DX_CLUSTER_HOST=dxspider.net
DX_CLUSTER_PORT=7300
DX_CLUSTER_CALLSIGN=YOUR_CALLSIGN # Replace with your callsign
# Auth0 Configuration
AUTH0_DOMAIN=your-tenant.auth0.com # From Auth0 dashboard
AUTH0_CLIENT_ID=your_client_id # From Auth0 dashboard
AUTH0_CLIENT_SECRET=your_secret # From Auth0 dashboard
AUTH0_AUDIENCE=https://dx-cluster-mcp-api # API Identifier from Step 5
AUTH0_CALLBACK_URL=http://localhost:8000/auth/callback
# Server Configuration
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
SERVER_BASE_URL=http://localhost:8000
# Logging
LOG_LEVEL=INFO
```
**Important Notes:**
- Replace `YOUR_CALLSIGN` with your actual amateur radio callsign
- Copy Auth0 credentials exactly from the dashboard
- Ensure no trailing spaces in values
### 4. Start the Server
```bash
# Build and start in detached mode
docker-compose up -d
# View logs to confirm startup
docker-compose logs -f dx-cluster-mcp
```
You should see output like:
```
INFO - Starting DX Cluster MCP Server
INFO - Authentication: Enabled (Auth0)
INFO - Starting server on 0.0.0.0:8000
```
Press `Ctrl+C` to exit logs (server continues running).
### 5. Verify Server is Running
```bash
# Check container status
docker-compose ps
# Test HTTP endpoint
curl http://localhost:8000
```
## Claude Desktop Integration
### 1. Locate Configuration File
On Windows, the config file is at:
```
%APPDATA%\Claude\claude_desktop_config.json
```
Full path example:
```
C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json
```
### 2. Edit Configuration
If the file doesn't exist, create it. Add the MCP server configuration:
```json
{
"mcpServers": {
"dx-cluster": {
"url": "http://localhost:8000/sse",
"transport": "sse"
}
}
}
```
**For remote server (different machine):**
```json
{
"mcpServers": {
"dx-cluster": {
"url": "http://YOUR_SERVER_IP:8000/sse",
"transport": "sse"
}
}
}
```
### 3. Restart Claude Desktop
1. Completely close Claude Desktop (check system tray)
2. Reopen Claude Desktop
3. Start a new conversation
### 4. Verify Connection
In Claude Desktop, try:
```
Show me the available MCP tools
```
You should see tools like:
- `read_spots`
- `create_spot`
- `analyze_spots`
- `get_band_activity`
- `cluster_info`
## Testing
### Test 1: Check Cluster Connection
In Claude Desktop:
```
Show cluster connection information
```
Expected response includes your callsign and cluster details.
### Test 2: Read Spots
```
Read the last 10 DX spots
```
You should receive a list of recent spots with callsigns, frequencies, and comments.
### Test 3: Analyze Band Activity
```
Which bands are most active right now?
```
Should return statistics about band activity.
### Test 4: Comprehensive Analysis
```
Analyze the last 50 spots and show me propagation trends
```
Should return detailed analysis including:
- Band activity
- DX entity statistics
- Hourly trends
- Rare DX alerts
### Test 5: Create a Spot (Optional)
```
Post a spot for W1AW on 14025 kHz with comment "Testing"
```
**Note:** Only do this if you actually hear the station!
## Production Deployment
### 1. Get a Domain Name
- Purchase or use existing domain
- Point to your server's IP address
### 2. Update Auth0 Settings
In Auth0 Dashboard, update Application URIs:
```
Allowed Callback URLs:
https://your-domain.com/auth/callback
http://localhost:8000/auth/callback
Allowed Logout URLs:
https://your-domain.com
http://localhost:8000
Allowed Web Origins:
https://your-domain.com
http://localhost:8000
```
### 3. Set Up HTTPS
Use a reverse proxy like Nginx with Let's Encrypt:
```nginx
server {
listen 443 ssl;
server_name your-domain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
### 4. Update Environment Variables
Update `.env` for production:
```bash
SERVER_BASE_URL=https://your-domain.com
AUTH0_CALLBACK_URL=https://your-domain.com/auth/callback
```
Restart the server:
```bash
docker-compose down
docker-compose up -d
```
### 5. Update Claude Desktop Config
```json
{
"mcpServers": {
"dx-cluster": {
"url": "https://your-domain.com/sse",
"transport": "sse"
}
}
}
```
## Troubleshooting
### Server Won't Start
```bash
# Check logs for errors
docker-compose logs dx-cluster-mcp
# Common issues:
# 1. Port 8000 already in use
# - Change SERVER_PORT in .env
# 2. Missing environment variables
# - Verify all required vars in .env
```
### Cannot Connect to Cluster
```bash
# Test cluster connectivity
telnet dxspider.net 7300
# If this fails, try a different cluster or check firewall
```
### Auth0 Errors
- Verify all URLs match exactly (http vs https)
- Check Client ID and Secret are correct
- Ensure no extra spaces in .env file
- Verify Auth0 domain is correct (include .auth0.com)
### Claude Desktop Not Seeing Server
1. Check config file path is correct
2. Ensure JSON is valid (use [JSONLint](https://jsonlint.com/))
3. Restart Claude Desktop completely
4. Check server is running: `docker-compose ps`
5. Test URL in browser: `http://localhost:8000`
### Docker Issues
```bash
# Rebuild from scratch
docker-compose down -v
docker-compose build --no-cache
docker-compose up -d
# Check Docker is running
docker --version
docker-compose --version
```
## Maintenance
### View Logs
```bash
# Follow logs in real-time
docker-compose logs -f
# View last 100 lines
docker-compose logs --tail=100
```
### Restart Server
```bash
docker-compose restart
```
### Update Server
```bash
# Pull latest code
git pull
# Rebuild and restart
docker-compose down
docker-compose up -d --build
```
### Backup Configuration
```bash
# Backup your .env file
cp .env .env.backup
# Store securely, it contains secrets!
```
## Next Steps
Once everything is working:
1. Explore the different analysis tools
2. Monitor which bands are active
3. Track rare DX opportunities
4. Share spots with the ham radio community
## Getting Help
- Check the main [README.md](README.md) for usage examples
- Review logs for error messages
- Verify all configuration settings
- Test each component independently
## Resources
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [Auth0 Documentation](https://auth0.com/docs)
- [Docker Documentation](https://docs.docker.com/)
- [DXSpider Info](http://www.dxspider.net/)
---
**73 and good DX!**
