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
- Clone or download this project
- 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 yearround_number(optional): Filter by round number
list_sessions
Fetch F1 sessions (practice, qualifying, race).
Parameters:
season(optional): Filter by season yearround_number(optional): Filter by round number
list_results
Fetch race results. Optionally filter by session or driver.
Parameters:
session_key(optional): Filter by session keydriver_number(optional): Filter by driver number
list_laps
Fetch lap data from a session.
Parameters:
session_key(optional): Session key for filteringdriver_number(optional): Filter by driver number
list_stints
Fetch stint data (tire stints).
Parameters:
session_key(optional): Session key for filteringdriver_number(optional): Filter by driver number
list_pit_stops
Fetch pit stop data from a session.
Parameters:
session_key(optional): Session key for filteringdriver_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 keydriver_number(optional): Filter by driver number
get_car_data
Fetch car telemetry data (throttle, brake, DRS, etc.).
Parameters:
session_key(optional): Session keydriver_number(optional): Filter by driver number
list_positions
Fetch position data (live positions during session).
Parameters:
session_key(optional): Session keydriver_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 clienttests/test_server.py- Tests for the MCP server and tool registrationtests/test_integration.py- Integration tests using the real API
Development
To extend the server with additional tools:
- Add new methods to
OpenF1Clientinsrc/openf1_client.py - Add corresponding tool definitions in
OpenF1MCPServer.get_tools()insrc/server.py - Add handling for the new tool in
_run_tool()method - Add tests in
tests/test_openf1_client.pyandtests/test_server.py
License
This project is open source and available under the MIT License.