Panth1823 formula1 mcp

A TypeScript-based Formula 1 MCP server, bringing the thrill of real-time and historical F1 racing data straight to your fingertips via the Model Context Protocol.

API Status: ✅ 21/22 OpenF1 endpoints + 10 Ergast endpoints working
Last Tested: November 10, 2025
Active Tools: 29 MCP tools (All historical data FREE, live streaming requires paid OpenF1 account)
Access: 🎉 No authentication required for historical data!

• ✅ Free historical data access - No authentication required!
• ✅ Comprehensive F1 data - Sessions, drivers, weather, telemetry (2023-present via OpenF1)
• ✅ Legacy data - Historical race information (1950-present via Ergast API)
• ✅ Access F1 session data via standardized REST APIs
• ✅ Real-time telemetry data (car speed, throttle, brake, RPM, DRS, gear)
• ✅ Driver and constructor standings
• ✅ Weather data (air/track temperature, humidity, wind, rainfall)
• ✅ Circuit information with coordinates
• ✅ Team radio communications with audio URLs
• ✅ Race control messages, flags, and penalties
• ✅ Pit stop data and tire strategy
• ✅ Lap times and sector analysis
• ✅ Position tracking and intervals
• ⚠️ Live streaming (MQTT) - Requires paid OpenF1 account (currently disabled)

All historical data is completely free! This includes:

• ✅ All sessions from 2023-present (OpenF1)
• ✅ All races from 1950-present (Ergast)
• ✅ Telemetry, lap times, positions, pit stops
• ✅ Team radio recordings, race control messages
• ✅ Weather data, driver info, overtakes
• ✅ Beta features: Session results, starting grid

Only real-time streaming during live races:

• ❌ MQTT WebSocket streaming (live updates)
• ❌ Real-time data during active F1 sessions
• 📝 Apply for paid access if needed

Note: REST API endpoints may still work during race weekends for delayed/recent data without a paid account (to be tested).

For detailed endpoint testing results, see OPENF1_API_ACCESS_REPORT.md.

1. Clone the repo:

git clone https://github.com/Panth1823/formula1-mcp
cd formula1-mcp

1. Install:

npm install

1. Build:

npm run build

That's it! No API keys or authentication required for historical data.

Add to your Claude Desktop config:

{
  "mcpServers": {
    "formula1": {
      "command": "node",
      "args": ["<path-to-your-cloned-repo>/build/index.js"],
      "cwd": "<path-to-your-cloned-repo>",
      "enabled": true
    }
  }
}

Config locations:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

These tools return live data during active F1 sessions (race weekends). When no session is active, they return empty arrays or last available data.

Note: Real-time MQTT streaming requires a paid OpenF1 account. REST API access during race weekends may work without payment (to be tested).

Get car telemetry for all drivers (speed, throttle, brake, RPM, DRS, gear).

Parameters: None
Returns: Array of car telemetry data (empty if no active session)
Free Access: ⚠️ To be tested during next race weekend

Get current track positions and gaps.

Parameters: None
Returns: Array of position data with gaps (empty if no active session)
Free Access: ⚠️ To be tested during next race weekend

Get recent race control messages (flags, penalties, safety car).

Parameters: None
Returns: Array of race control messages
Data Source: MQTT stream (live) or REST API (fallback)

Get recent team radio communications with audio URLs.

Parameters: None
Returns: Array of team radio messages
Data Source: MQTT stream (live) or REST API (fallback)

Get current weather conditions.

Parameters: None
Returns: Weather data object
Data Source: MQTT stream (live) or REST API (fallback)

Check streaming connection status and data availability.

Parameters: None
Returns: Connection status and data counters

Manually start the MQTT streaming connection.

Parameters: None
Requires: MQTT_ENABLED=true and valid credentials

Stop streaming and clear live data cache.

Parameters: None

Get real-time lap timing data for the current/latest session. Now uses streaming when active!

Parameters:

• None required

Note: Returns live data from MQTT stream if active, otherwise uses REST API. May return empty if no live session is active.

Get status information about the current session.

Parameters:

• None required

⚠️ Warning: This endpoint may not work reliably. OpenF1 API doesn't have a standard /session_status endpoint.

Get real-time driver information from OpenF1 (requires session context).

Parameters:

• driverId (string): Driver number (e.g., "1", "44", "33")

Note: For historical driver data, use getDriverInformation instead.

Find session keys for historical events. You MUST use this first to get session_key values needed for other tools.

Parameters:

• year (number, optional): Season year (e.g., 2023, 2024)
• circuit_short_name (string, optional): Circuit name (e.g., "Monaco", "Silverstone", "Monza")
• country_name (string, optional): Country name (e.g., "Italy", "Belgium")
• session_name (string, optional): Session type (e.g., "Race", "Qualifying", "Practice 1")

Example: Find 2024 Monaco Race: year=2024, circuit_short_name="Monaco", session_name="Race"

Get race results for a specific historical race.

Parameters:

• year (number): Season year (e.g., 2023)
• round (number): Race number (e.g., 1, 2, 3)

Get driver championship standings.

Parameters:

• year (number): Season year (e.g., 2023)

Get constructor championship standings.

Parameters:

• year (number): Season year (e.g., 2023)

Get lap times for a specific driver.

Parameters:

• year (number): Season year (e.g., 2023)
• round (number): Race number (e.g., 1, 2, 3)
• driverId (string): Driver identifier (e.g., "max_verstappen", "lewis_hamilton")

Get weather data for a session.

Parameters:

• sessionKey (string, REQUIRED): Session identifier from getHistoricalSessions

Returns: Air/track temperature, humidity, pressure, wind speed/direction, rainfall

Get detailed car telemetry data.

Parameters:

• driverNumber (string, REQUIRED): Driver's car number (e.g., "1", "44", "33")
• sessionKey (string, REQUIRED): Session identifier from getHistoricalSessions
• filters (string, optional): Additional filters (e.g., "speed>=300")

Returns: Speed, throttle %, brake status, RPM, gear, DRS status (18K+ data points per session)

Get pit stop information.

Parameters:

• driverNumber (string, optional): Driver's car number
• sessionKey (string, optional): Session identifier

Get team radio communications.

Parameters:

• sessionKey (string, REQUIRED): Session identifier from getHistoricalSessions
• driverNumber (string, optional): Driver's car number to filter

Returns: Radio message URLs and timestamps

Get race control messages (flags, incidents, safety car periods).

Parameters:

• sessionKey (string, REQUIRED): Session identifier from getHistoricalSessions

Returns: Messages, categories, flags (yellow, red, safety car), driver numbers affected

Get the F1 race calendar.

Parameters:

• year (number): Season year (e.g., 2023)

Get detailed circuit information.

Parameters:

• circuitId (string): Circuit identifier (e.g., "monza", "spa")

Get a list of available F1 seasons.

Parameters:

• limit (number, optional): Number of seasons to return

Get qualifying session results.

Parameters:

• year (number): Season year (e.g., 2023)
• round (number): Race number (e.g., 1, 2, 3)

Get detailed driver information from Ergast API.

Parameters:

• driverId (string): Driver identifier (e.g., "max_verstappen", "lewis_hamilton")

Get detailed constructor information from Ergast API.

Parameters:

• constructorId (string): Constructor identifier (e.g., "red_bull", "mercedes")

Clear the local cache for F1 data.

Parameters:

• None required

• Live Streaming: OpenF1 MQTT - Real-time MQTT/WebSocket streaming with OAuth2
• Live/Recent Data: OpenF1 API - Real-time telemetry, positions, weather (REST)
• Historical Data: Ergast API - Complete F1 history (1950-2024)

Important: Ergast API is scheduled to stop updates after 2024 season. Plan for alternative historical sources for 2025+.

• QUICK_START_STREAMING.md - Get started with live streaming in 5 minutes
• LIVE_DATA_IMPLEMENTATION.md - Complete technical documentation
• COMPREHENSIVE_TEST_RESULTS.md - API test results and validation
• API_USAGE_ANALYSIS.md - Feature usage analysis

1. getCurrentSessionStatus - May not work reliably (endpoint doesn't exist in official OpenF1 API)
2. Monaco 2024 - Returns 0 sessions (data may not be available for all circuits)
3. Sprint Races - Not yet supported (Ergast endpoint returns rate limits)

Live Streaming (NEW!):

• "What are the current positions in the race?" → Use getLivePositions
• "Show me live telemetry for Verstappen" → Use getLiveCarData
• "Latest race control messages" → Use getLiveRaceControl
• "Current weather conditions" → Use getLiveWeather
• "Is streaming active?" → Use getStreamingStatus

Finding a Session:

• "Find the 2024 Bahrain Grand Prix race session" → Use getHistoricalSessions
• "Get session key for 2023 Monaco qualifying" → Use getHistoricalSessions

Historical Queries:

• "Show 2023 Monaco GP results" → Use getHistoricRaceResults
• "Get current 2024 standings" → Use getDriverStandings + getConstructorStandings
• "Hamilton's lap times at Silverstone 2023" → Use getLapTimes

Live Data (requires session_key):

• "Weather at Silverstone" → Use getHistoricalSessions then getWeatherData
• "Verstappen's telemetry" → Use getCarData with driver number and session key
• "Team radio messages" → Use getTeamRadio with session key

General Info:

• "Show 2024 calendar" → Use getRaceCalendar
• "Tell me about Lewis Hamilton" → Use getDriverInformation
• "Info about Monza circuit" → Use getCircuitInfo

Use MCP Inspector for debugging.

The project includes comprehensive API testing with real-world validation:

# Test OpenF1 API (12 tests)
npm run test:openf1

# Test Ergast API (14 tests)  
npm run test:ergast

# Test both APIs (26 tests)
npm run test:apis

Latest Test Results: ✅ 26/26 tests passing (100%)
See COMPREHENSIVE_TEST_RESULTS.md for detailed results.

• Bugs? Report here
• Questions? Open an issue
• Want to help? Submit a PR

This project is licensed under the MIT License - see the LICENSE file for details.