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:

python -m src.server

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

{
  "mcpServers": {
    "openf1": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/openf1_mcp"
    }
  }
}

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

openf1_mcp/
├── src/
│   ├── __init__.py
│   ├── server.py           # Main MCP server implementation
│   ├── openf1_client.py    # OpenF1 API client
├── tests/
│   ├── __init__.py
│   ├── conftest.py         # Pytest configuration
│   ├── test_openf1_client.py   # Client unit tests
│   ├── test_server.py          # Server unit tests
│   └── test_integration.py     # Integration tests
├── requirements.txt        # Python dependencies
├── pytest.ini             # Pytest configuration
├── run_tests.py           # Test runner script
└── README.md              # This file

Testing

The project includes comprehensive unit and integration tests.

Running Tests

Unit tests only:

python -m pytest tests/

Unit tests with coverage:

python -m pytest tests/ --cov=src --cov-report=html

Integration tests (requires API access):

python -m pytest tests/ --integration

Using the test runner script:

python run_tests.py                    # Run unit tests
python run_tests.py --integration      # Run all tests including integration
python run_tests.py --coverage         # Run unit tests with coverage report
python run_tests.py --integration --coverage  # Run all tests with coverage

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.