# F1 MCP Server

> **Advanced Formula 1 Data Analysis MCP Server** - Real-time telemetry, tire performance analysis, and race strategy simulation for Claude

A sophisticated Model Context Protocol (MCP) server that provides Claude with advanced Formula 1 analytics capabilities, including real-time telemetry processing, tire degradation modeling, weather impact analysis, and Monte Carlo race strategy simulation.

## 🏎️ Features

### **12 Powerful F1 Analysis Tools**

#### **Core Analysis Tools (8)**
- **Session Data Analysis** - Comprehensive race weekend data with telemetry and weather
- **Tire Performance Analysis** - Advanced degradation modeling with thermal analysis  
- **Lap Time Analysis** - Fuel-corrected analysis with 25 mini-sector breakdown
- **Weather Impact Prediction** - LSTM/CNN forecasting with strategic recommendations
- **Race Strategy Simulation** - Monte Carlo simulation with 300M-1B+ permutations
- **Driver Performance Analysis** - Skill extraction separating car vs. driver performance
- **Real-time Telemetry Processing** - Advanced signal analysis with anomaly detection
- **Sector Performance Analysis** - 25 mini-sector analysis with track curvature correlation

#### **2025 Live Data Tools (4)**
- **Current Season Info** - Live F1 season data with real-time status
- **Race Schedule** - Complete F1 calendar for 2018-2025 seasons
- **Live Timing Connection** - F1 Official Live Timing API integration
- **API Status Monitoring** - Real-time status of all F1 data sources

### **Advanced Analytics Capabilities**
- **Mathematical Models**: Sophisticated tire degradation physics with thermal, mechanical, and chemical factors
- **Signal Processing**: FFT, wavelet analysis, and Kalman filtering for telemetry data
- **Weather Modeling**: Ensemble forecasting with LSTM/CNN hybrid models
- **Strategy Optimization**: Monte Carlo simulation with probabilistic outcomes and risk analysis
- **Performance Extraction**: Driver skill analysis with 88%/12% car/driver performance split

## 📋 Prerequisites

- **Node.js** 18.0.0 or higher
- **npm** (comes with Node.js)
- **Claude Desktop** application

## 🚀 Installation

### Step 1: Clone and Setup the Server

```bash
# Clone the repository
git clone https://github.com/stagsz/F1-MCP-Server
cd F1-mcp-server

# Install dependencies
npm install

# Verify installation
npm test
```

### Step 2: Configure Claude Desktop

You need to add this MCP server to your Claude Desktop configuration file.

#### **Windows**
Edit the file at: `%APPDATA%\Claude\claude_desktop_config.json`

#### **macOS**
Edit the file at: `~/Library/Application Support/Claude/claude_desktop_config.json`

#### **Linux**
Edit the file at: `~/.config/Claude/claude_desktop_config.json`

### Step 3: Add Server Configuration

Add the following configuration to your `claude_desktop_config.json` file:

```json
{
  "mcpServers": {
    "f1-mcp-server": {
      "command": "node",
      "args": ["path/to/F1-mcp-server/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

**Important**: Replace `path/to/F1-mcp-server/index.js` with the absolute path to your F1-mcp-server directory.

#### Example configurations:

**Windows:**
```json
{
  "mcpServers": {
    "f1-mcp-server": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\F1-mcp-server\\index.js"]
    }
  }
}
```

**macOS/Linux:**
```json
{
  "mcpServers": {
    "f1-mcp-server": {
      "command": "node", 
      "args": ["/home/username/F1-mcp-server/index.js"]
    }
  }
}
```

### Step 4: Restart Claude Desktop

After saving the configuration file, completely quit and restart Claude Desktop for the changes to take effect.

## 🔧 Verification

Once Claude Desktop restarts, you can verify the F1 MCP Server is working by asking Claude:

```
Can you analyze tire performance for a Formula 1 race?
```

Claude should now have access to all F1 analysis capabilities and will use the MCP server to provide detailed analytics.

## 📚 Usage Examples

### **Tire Performance Analysis**
```
Analyze tire degradation for Lewis Hamilton using medium compound tires in the 2024 Monaco Grand Prix race session.
```

### **Race Strategy Simulation**
```
Run a Monte Carlo simulation comparing one-stop vs two-stop strategies for Max Verstappen at Silverstone 2024.
```

### **Weather Impact Analysis**
```
Predict weather impact for the next 3 hours during qualifying at Spa-Francorchamps and recommend tire strategy.
```

### **Driver Performance Analysis**
```
Analyze Charles Leclerc's driving performance and extract his skill level compared to car performance at Monza 2024.
```

### **Lap Time Analysis**
```
Perform fuel-corrected lap time analysis for George Russell in Practice 2, including mini-sector breakdown.
```

### **Real-time Telemetry**
```
Process real-time telemetry data for Fernando Alonso focusing on speed, throttle, and brake channels.
```

## 🛠️ Development

### **Testing**
```bash
# Run test suite
npm test

# Run tests with coverage
npm run test -- --coverage

# Check syntax
node --check index.js
```

### **Development Mode**
```bash
# Start with auto-reload
npm run dev

# Check logs
tail -f logs/combined.log
```

### **Debugging**
```bash
# Enable debug logging
export LOG_LEVEL=debug
npm start
```

## 📊 Technical Specifications

### **Data Processing**
- **Telemetry Volume**: 1.1M+ data points per second simulation
- **Sampling Rate**: 100Hz simulation  
- **Monte Carlo**: 300M to 1B+ permutations per race
- **Signal Processing**: FFT, wavelet analysis, Kalman filtering

### **Mathematical Models**
- **Tire Degradation**: Thermal, mechanical, and chemical factors
- **Weather Forecasting**: LSTM/CNN ensemble models
- **Driver Analysis**: 88%/12% car/driver performance split
- **Strategy Optimization**: Probabilistic outcome modeling

### **Supported F1 Data & Live Integration**
- **Years**: 2018-2025 (including current 2025 season)
- **Sessions**: Practice 1-3, Qualifying, Sprint, Race
- **Data Sources**: F1 Live Timing → OpenF1 API → Ergast API → Advanced Simulation
- **Live Data**: Real-time telemetry during active F1 sessions
- **Tire Compounds**: C1-C6, Soft/Medium/Hard, Intermediates, Wets
- **Weather**: Live conditions, temperature, humidity, rain probability, wind
- **Telemetry**: Speed, throttle, brake, DRS, gear, RPM, tire temps, GPS coordinates

## 🚨 Troubleshooting

### **Server Not Starting**
```bash
# Check Node.js version
node --version  # Should be 18.0.0+

# Verify dependencies
npm install

# Check syntax
node --check index.js
```

### **Claude Can't Find Server**
1. Verify the path in `claude_desktop_config.json` is absolute and correct
2. Ensure Claude Desktop was completely restarted after config changes
3. Check that Node.js is in your system PATH

### **Permission Issues (macOS/Linux)**
```bash
# Make index.js executable
chmod +x index.js

# Check file permissions
ls -la index.js
```

### **Dependencies Issues**
```bash
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
```

## 📖 Complete Tool Documentation

### **Core Analysis Tools**

#### 🏁 `get_session_data`
**Get comprehensive F1 session data including telemetry, timing, and weather**

**Parameters:**
- `year` (required): Race year (2018-2025)
- `round` (required): Race round number (1-24)
- `session` (required): Session type
  - `Practice 1`, `Practice 2`, `Practice 3`
  - `Qualifying`, `Sprint`, `Race`

**Example:**
```
Get session data for 2024 Monaco Grand Prix qualifying
```

**Returns:** Comprehensive session overview with lap times, weather conditions, tire usage, and telemetry summaries.

---

#### 🏎️ `analyze_tire_performance`
**Advanced tire performance analysis with degradation modeling and strategy insights**

**Parameters:**
- `year` (required): Race year
- `round` (required): Race round number
- `session` (required): Session type
- `driver` (optional): Driver abbreviation (HAM, VER, LEC, etc.)
- `compound` (optional): Tire compound (SOFT, MEDIUM, HARD)

**Example:**
```
Analyze tire degradation for Lewis Hamilton using medium compound tires in the 2024 Monaco Grand Prix race session
```

**Returns:** Detailed tire analysis including:
- Degradation curves with thermal modeling
- Grip loss patterns and optimal stint lengths
- Strategic recommendations for tire changes
- Performance comparison across compounds

---

#### ⏱️ `analyze_lap_times`
**Sophisticated lap time analysis with fuel correction and mini-sector breakdown**

**Parameters:**
- `year` (required): Race year
- `round` (required): Race round number
- `session` (required): Session type
- `driver` (optional): Driver abbreviation
- `fuel_corrected` (optional): Apply fuel correction (default: true)

**Example:**
```
Perform fuel-corrected lap time analysis for George Russell in Practice 2, including mini-sector breakdown
```

**Returns:** Advanced lap time analysis featuring:
- Fuel-corrected lap times and pace analysis
- 25 mini-sector performance breakdown
- Track evolution and session progression
- Comparative analysis vs field

---

#### 🌦️ `predict_weather_impact`
**Weather impact analysis and prediction for race strategy**

**Parameters:**
- `year` (required): Race year
- `round` (required): Race round number
- `session` (required): Session type
- `forecast_hours` (optional): Forecast window in hours (default: 3)

**Example:**
```
Predict weather impact for the next 3 hours during qualifying at Spa-Francorchamps and recommend tire strategy
```

**Returns:** Comprehensive weather analysis including:
- LSTM/CNN ensemble weather forecasting
- Rain probability and intensity predictions
- Strategic recommendations for tire choices
- Timing windows for optimal track conditions

---

#### 🎯 `simulate_race_strategy`
**Monte Carlo race strategy simulation with probabilistic outcomes**

**Parameters:**
- `year` (required): Race year
- `round` (required): Race round number
- `driver` (required): Driver abbreviation
- `strategy_options` (optional): Array of strategies (e.g., ["soft-medium", "medium-hard"])
- `simulations` (optional): Number of Monte Carlo simulations (default: 10,000)

**Example:**
```
Run a Monte Carlo simulation comparing one-stop vs two-stop strategies for Max Verstappen at Silverstone 2024
```

**Returns:** Detailed strategy analysis featuring:
- Monte Carlo simulation with 300M-1B+ permutations
- Probabilistic outcomes and success rates
- Risk analysis and optimal pit windows
- Strategy recommendations with confidence intervals

---

#### 👨‍💼 `analyze_driver_performance`
**Driver performance extraction separating skill from car performance**

**Parameters:**
- `year` (required): Race year
- `round` (required): Race round number
- `session` (required): Session type
- `driver` (required): Driver abbreviation
- `comparison_driver` (optional): Driver to compare against

**Example:**
```
Analyze Charles Leclerc's driving performance and extract his skill level compared to car performance at Monza 2024
```

**Returns:** Advanced driver analysis including:
- Skill extraction with 88%/12% car/driver performance split
- Driving style analysis and performance metrics
- Comparison vs teammate or specified driver
- Strengths and improvement areas identification

---

#### 📡 `get_real_time_telemetry`
**Real-time telemetry data processing with advanced signal analysis**

**Parameters:**
- `year` (required): Race year
- `round` (required): Race round number
- `session` (required): Session type
- `driver` (required): Driver abbreviation
- `lap` (optional): Specific lap number
- `channels` (optional): Array of telemetry channels to analyze

**Available Channels:**
- `Speed`, `Throttle`, `Brake`, `DRS`, `Gear`, `RPM`
- `TireTemp`, `BrakeTemp`, `GPS`, `EngineTemp`

**Example:**
```
Process real-time telemetry data for Fernando Alonso focusing on speed, throttle, and brake channels
```

**Returns:** Comprehensive telemetry analysis featuring:
- High-frequency data processing (100Hz simulation)
- FFT, wavelet analysis, and Kalman filtering
- Anomaly detection and performance optimization
- Comparative analysis and setup recommendations

---

#### 🏁 `analyze_sector_performance`
**25 mini-sector analysis with track curvature correlation**

**Parameters:**
- `year` (required): Race year
- `round` (required): Race round number
- `session` (required): Session type
- `driver` (optional): Driver abbreviation

**Example:**
```
Analyze sector performance for all drivers in 2024 Hungarian Grand Prix qualifying with track curvature correlation
```

**Returns:** Detailed sector analysis including:
- 25 mini-sector performance breakdown
- Track curvature and elevation correlation
- Speed trap analysis and cornering performance
- Sector-specific setup and driving recommendations

---

### **2025 Live Data Tools**

#### 📅 `get_current_season_info`
**Get current F1 season information including live data availability**

**Parameters:**
- `include_live_status` (optional): Include live session status (default: true)

**Example:**
```
Get current F1 season information with live data status
```

**Returns:** Current season overview with live data availability status.

---

#### 🗓️ `get_race_schedule`
**Get F1 race schedule for any year including 2025**

**Parameters:**
- `year` (required): Race year (2018-2025)

**Example:**
```
Get the complete 2025 F1 race schedule
```

**Returns:** Complete race calendar with dates, venues, and session schedules.

---

#### 🔴 `connect_live_timing`
**Connect to F1 Official Live Timing API for real-time data**

**Parameters:** None

**Example:**
```
Connect to F1 Official Live Timing API
```

**Returns:** Live timing connection status and available real-time data feeds.

---

#### 📊 `get_live_timing_status`
**Get status of F1 Live Timing API connection**

**Parameters:** None

**Example:**
```
Check F1 Live Timing connection status
```

**Returns:** Current connection status and available live data streams.

---

#### 🔍 `get_api_status`
**Get status of all F1 data APIs (Ergast, OpenF1, Live Timing)**

**Parameters:** None

**Example:**
```
Check status of all F1 data APIs and get recommendations
```

**Returns:** Comprehensive API status report with recommendations for optimal data sources.

### **Session Types**
- `Practice 1`, `Practice 2`, `Practice 3`
- `Qualifying`, `Sprint`, `Race`

### **Driver Abbreviations**
- `HAM` (Hamilton), `VER` (Verstappen), `LEC` (Leclerc)
- `RUS` (Russell), `NOR` (Norris), `PER` (Perez)
- And all other F1 drivers...

## 🔄 Updates

To update the F1 MCP Server:

```bash
# Pull latest changes
git pull origin main

# Install any new dependencies  
npm install

# Run tests to verify
npm test

# Restart Claude Desktop
```

## 📄 License

MIT License - See LICENSE file for details.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📞 Support

For issues and questions:
- Check the troubleshooting section above
- Review the logs in `logs/combined.log` and `logs/error.log`
- Open an issue on GitHub with detailed error messages

---

**Ready to revolutionize your F1 analysis with Claude!** 🏁