praneethravuri/pitstop

Pitstop 🏎️

Comprehensive Formula 1 data via Model Context Protocol (MCP) for Claude Desktop

Production-ready MCP server with 25 optimized F1 data tools, comprehensive logging, health checks, and flexible configuration. Aggregates data from 4 free sources (FastF1, OpenF1, Ergast, 25+ RSS feeds) covering Formula 1 from 1950 to present.

🚀 Quick Start

Installation

git clone https://github.com/praneethravuri/pitstop.git
cd pitstop
uv sync

# Optional: Configure environment variables
cp .env.example .env
# Edit .env to customize settings

Configure Claude Desktop

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pitstop": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/pitstop",
        "mcp",
        "run",
        "/absolute/path/to/pitstop/server.py"
      ]
    }
  }
}

Note: Replace /absolute/path/to/pitstop with your installation path. Use double backslashes (\\) on Windows.

Restart Claude Desktop to activate.

📊 Data Sources

Note: RSS feeds only contain recent articles. For historical F1 news (e.g., 2013 Indian GP), use web search instead.

🛠️ Available Tools

Core Session Data

Telemetry & Analysis

Race Control & Track

Note: get_race_control_messages supports filtering with message_type: "all", "penalties", "investigations", "flags", "safety_car"

Live Timing - OpenF1

Championship & Schedule

Reference & Media

Parameter Conventions:

• year: Season year (2018+ for FastF1, 1950+ for Ergast, 2023+ for OpenF1)
• gp: Grand Prix name (e.g., "Monaco", "Silverstone") or round number
• session: Session type - "FP1", "FP2", "FP3", "Q", "S", "R"
• driver: 3-letter code (e.g., "VER") or driver number
• ? suffix: Optional parameter

💡 Usage Examples

# Session Analysis
"Get qualifying results from Monaco 2024"
"What was Verstappen's tire strategy in the race?"
"Show me sector times for all drivers"

# Telemetry
"Compare telemetry between Verstappen and Hamilton in qualifying"
"Get Leclerc's fastest lap data"

# Race Control
"What penalties were given in Monaco?"
"Show me all flag periods from the race"
"Get safety car periods"

# Live Data
"Get team radio messages from the race"
"Show me pit stop times for all drivers"
"What was the gap between Verstappen and Hamilton?"

# News & Schedule (Recent only)
"What's the latest F1 news?"
"Show me recent news about Ferrari"
"What are the transfer rumors this week?"
"When is the next race?"

# Note: For historical news (e.g., "2013 Indian GP"), use web search

⚙️ Configuration

Environment Variables (.env)

Pitstop uses environment variables for configuration. A .env file is included for easy setup:

# Copy the example file and customize
cp .env.example .env

Available Configuration Options:

Production Mode (PITSTOP_ENV=production):

• ✅ Structured JSON logging for log aggregation
• ✅ Error message masking for security
• ✅ Optimized performance settings
• ✅ Health check resources enabled

Development Mode (PITSTOP_ENV=development):

• ✅ Human-readable text logging
• ✅ Detailed error messages with stack traces
• ✅ Debug-level logging by default
• ✅ Full error context for debugging

Cache Management

FastF1 caches session data in cache/ for performance. Clear if needed:

rm -rf cache/     # Unix/macOS
rmdir /s cache    # Windows

Health Check

Access server status and health information via the server://status resource:

{
  "server": "Pitstop F1 MCP Server",
  "version": "1.0.0",
  "status": "operational",
  "environment": "production",
  "tools_count": 25,
  "data_sources": {
    "fastf1": "operational (2018-present)",
    "openf1": "operational (2023-present)",
    "ergast": "operational (1950-2024)",
    "rss_feeds": "operational (25+ sources)"
  }
}

🧪 Testing

Test individual tools:

# Test session tool
python tools/session/results.py

# Test telemetry
python tools/telemetry/lap_telemetry.py

# Test OpenF1 live data
python tools/live/radio.py

# Test race control
python tools/control/messages.py

🤝 Contributing

Contributions welcome! Please submit a Pull Request.

📄 License

MIT License - see file

🙏 Acknowledgments

• FastF1 - Formula 1 data library
• OpenF1 - Real-time F1 data API
• Ergast API - Historical F1 database
• Model Context Protocol - MCP specification

Built with ❤️ for F1 fans and data enthusiasts