OpenF1 MCP Server

A Model Context Protocol (MCP) server that connects to the openF1.org API to fetch Formula 1 data. This server uses the stdio transport method for communication.

Features

The MCP server provides tools to fetch various Formula 1 data:

• Drivers - Get driver information, filter by season or driver number

• Teams - Fetch team data for specific seasons

• Races - Get race information by season or round

• Sessions - Fetch practice, qualifying, and race sessions

• Results - Get race results filtered by session or driver

• Laps - Fetch lap-by-lap data from sessions

• Stints - Get tire stint information

• Pit Stops - Access pit stop data

• Weather - Fetch weather conditions during sessions

• Incidents - Get penalty and collision data

• Car Data - Access telemetry data (throttle, brake, DRS, etc.)

• Positions - Get live position data during sessions

Installation

1. Clone or download this project

2. Install dependencies:

   pip install -r requirements.txt

Usage

Running the Server

Start the MCP server using stdio transport:

Connecting via Claude

To use this server with Claude Desktop, add it to your claude_desktop_config.json:

macOS/Linux: ~/.config/claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Available Tools

list_drivers

Fetch F1 drivers. Optionally filter by season or driver number.

Parameters:

• season (optional): Filter by season year (e.g., 2024)

• driver_number (optional): Filter by driver number

list_teams

Fetch F1 teams. Optionally filter by season.

Parameters:

• season (optional): Filter by season year (e.g., 2024)

list_races

Fetch F1 races. Optionally filter by season or round number.

Parameters:

• season (optional): Filter by season year

• round_number (optional): Filter by round number

list_sessions

Fetch F1 sessions (practice, qualifying, race).

Parameters:

• season (optional): Filter by season year

• round_number (optional): Filter by round number

list_results

Fetch race results. Optionally filter by session or driver.

Parameters:

• session_key (optional): Filter by session key

• driver_number (optional): Filter by driver number

list_laps

Fetch lap data from a session.

Parameters:

• session_key (optional): Session key for filtering

• driver_number (optional): Filter by driver number

list_stints

Fetch stint data (tire stints).

Parameters:

• session_key (optional): Session key for filtering

• driver_number (optional): Filter by driver number

list_pit_stops

Fetch pit stop data from a session.

Parameters:

• session_key (optional): Session key for filtering

• driver_number (optional): Filter by driver number

get_weather

Fetch weather data for a session.

Parameters:

• session_key: Session key

list_incidents

Fetch incident data (collisions, penalties, etc.).

Parameters:

• session_key (optional): Session key

• driver_number (optional): Filter by driver number

get_car_data

Fetch car telemetry data (throttle, brake, DRS, etc.).

Parameters:

• session_key (optional): Session key

• driver_number (optional): Filter by driver number

list_positions

Fetch position data (live positions during session).

Parameters:

• session_key (optional): Session key

• driver_number (optional): Filter by driver number

API Reference

This project uses the openF1.org API which provides:

• No authentication required

• Free to use

• Open source data from Formula 1

For more information about the API, visit openf1.org

Project Structure

Testing

The project includes comprehensive unit and integration tests.

Running Tests

Unit tests only:

Unit tests with coverage:

Integration tests (requires API access):

Using the test runner script:

Test Files

• tests/test_openf1_client.py - Tests for the OpenF1 API client

• tests/test_server.py - Tests for the MCP server and tool registration

• tests/test_integration.py - Integration tests using the real API

Development

To extend the server with additional tools:

1. Add new methods to OpenF1Client in src/openf1_client.py

2. Add corresponding tool definitions in OpenF1MCPServer.get_tools() in src/server.py

3. Add handling for the new tool in _run_tool() method

4. Add tests in tests/test_openf1_client.py and tests/test_server.py

License

This project is open source and available under the MIT License.