# OpenF1 MCP Server
A Model Context Protocol (MCP) server that connects to the [openF1.org](https://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:
```bash
pip install -r requirements.txt
```
## Usage
### Running the Server
Start the MCP server using stdio transport:
```bash
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`
```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](https://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:**
```bash
python -m pytest tests/
```
**Unit tests with coverage:**
```bash
python -m pytest tests/ --cov=src --cov-report=html
```
**Integration tests (requires API access):**
```bash
python -m pytest tests/ --integration
```
**Using the test runner script:**
```bash
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.
