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