README - F1-MCP-Server by stagsz

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

# Clone the repository
git clone <repository-url>
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:

{
  "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:

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

macOS/Linux:

{
  "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

# Run test suite
npm test

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

# Check syntax
node --check index.js

Development Mode

# Start with auto-reload
npm run dev

# Check logs
tail -f logs/combined.log

Debugging

# 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

# 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

Verify the path in claude_desktop_config.json is absolute and correct
Ensure Claude Desktop was completely restarted after config changes
Check that Node.js is in your system PATH

Permission Issues (macOS/Linux)

# Make index.js executable
chmod +x index.js

# Check file permissions
ls -la index.js

Dependencies Issues

# 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:

# 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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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! 🏁

stagsz/F1-MCP-Server

F1 MCP Server

🏎️ Features

12 Powerful F1 Analysis Tools

Core Analysis Tools (8)

2025 Live Data Tools (4)

Advanced Analytics Capabilities

📋 Prerequisites

🚀 Installation

Step 1: Clone and Setup the Server

Step 2: Configure Claude Desktop

Windows

macOS

Linux

Step 3: Add Server Configuration

Example configurations:

Step 4: Restart Claude Desktop

🔧 Verification

📚 Usage Examples

Tire Performance Analysis

Race Strategy Simulation

Weather Impact Analysis

Driver Performance Analysis

Lap Time Analysis

Real-time Telemetry

🛠️ Development

Testing

Development Mode

Debugging

📊 Technical Specifications

Data Processing

Mathematical Models

Supported F1 Data & Live Integration

🚨 Troubleshooting

Server Not Starting

Claude Can't Find Server

Permission Issues (macOS/Linux)

Dependencies Issues

📖 Complete Tool Documentation

Core Analysis Tools

🏁 get_session_data

🏎️ analyze_tire_performance

⏱️ analyze_lap_times

🌦️ predict_weather_impact

🎯 simulate_race_strategy

👨‍💼 analyze_driver_performance

📡 get_real_time_telemetry

🏁 analyze_sector_performance

2025 Live Data Tools

📅 get_current_season_info

🗓️ get_race_schedule

🔴 connect_live_timing

📊 get_live_timing_status

🔍 get_api_status

Session Types

Driver Abbreviations

🔄 Updates

📄 License

🤝 Contributing

📞 Support

🏁 `get_session_data`

🏎️ `analyze_tire_performance`

⏱️ `analyze_lap_times`

🌦️ `predict_weather_impact`

🎯 `simulate_race_strategy`

👨‍💼 `analyze_driver_performance`

📡 `get_real_time_telemetry`

🏁 `analyze_sector_performance`

📅 `get_current_season_info`

🗓️ `get_race_schedule`

🔴 `connect_live_timing`

📊 `get_live_timing_status`

🔍 `get_api_status`