Skip to content

Panth1823/formula1-mcp

BranchesTags

Repository files navigation

MseeP.ai Security Assessment Badge

The Formula1 MCP Server ! 🏎️💨

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!

Features

  • ✅ 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)

📊 API Access & Pricing

What's Free? (No Account Needed) ✅

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

What Requires a Paid Account? ⚠️

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.

Getting Started

Installation

  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.

Usage

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

Available Tools

🏎️ Live Data Tools

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).

1. getLiveCarData

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

2. getLivePositions

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

3. getLiveRaceControl

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)

4. getLiveTeamRadio

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)

5. getLiveWeather

Get current weather conditions.

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

6. getStreamingStatus

Check streaming connection status and data availability.

Parameters: None
Returns: Connection status and data counters

7. startStreaming

Manually start the MQTT streaming connection.

Parameters: None
Requires: MQTT_ENABLED=true and valid credentials

8. stopStreaming

Stop streaming and clear live data cache.

Parameters: None

Historical Data Tools

1. getLiveTimingData (Enhanced)

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.

2. getCurrentSessionStatus

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.

3. getDriverInfo

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.

4. getHistoricalSessions ⭐ CRITICAL

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"

5. getHistoricRaceResults

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)

6. getDriverStandings

Get driver championship standings.

Parameters:

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

7. getConstructorStandings

Get constructor championship standings.

Parameters:

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

8. getLapTimes

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

9. getWeatherData

Get weather data for a session.

Parameters:

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

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

10. getCarData

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)

11. getPitStopData

Get pit stop information.

Parameters:

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

12. getTeamRadio

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

13. getRaceControlMessages

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

14. getRaceCalendar

Get the F1 race calendar.

Parameters:

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

15. getCircuitInfo

Get detailed circuit information.

Parameters:

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

16. getSeasonList

Get a list of available F1 seasons.

Parameters:

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

17. getQualifyingResults

Get qualifying session results.

Parameters:

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

18. getDriverInformation

Get detailed driver information from Ergast API.

Parameters:

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

19. getConstructorInformation

Get detailed constructor information from Ergast API.

Parameters:

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

20. clearCache

Clear the local cache for F1 data.

Parameters:

  • None required

Data Sources

  • 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+.

Documentation

Known Issues

  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)

Examples

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

Debug

Use MCP Inspector for debugging.

Testing

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.

Help

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

License

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

About

server.smithery.ai/@Panth1823/formula1-mcp/mcp

Topics

typescript formula1 ai-agents mcp-server

Resources

Readme

License

MIT license
Activity

Stars

12 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

Languages