# f1-mcp

An MCP server exposing Formula 1 historical data (results, qualifying, pit stops, and
championship standings) as tools an LLM can call directly — built on the
[Jolpica-F1 API](https://github.com/jolpica/jolpica-f1).

## Tools (more to be added)

| Tool                        | Description                                                |
| --------------------------- | ---------------------------------------------------------- |
| `get_race_results`          | Race results by season + round number                      |
| `get_race_results_by_name`  | Race results by season + race/circuit name (e.g. "Monaco") |
| `get_qualifying_results`    | Qualifying results by season + round                       |
| `get_pit_stops`             | Pit stop log for a race (2011 season onward)               |
| `get_driver_standings`      | Drivers' championship standings for a season               |
| `get_constructor_standings` | Constructors' championship standings for a season          |

## Setup

```bash
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
```

## Running it

Standalone, with MCP Inspector (for testing tools/prompts manually):

```bash
npx @modelcontextprotocol/inspector python src/server.py
```

With Claude Desktop, add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "f1-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/f1-mcp/src/server.py"]
    }
  }
}
```

## Design notes

- **`client.py` is the only file that touches raw Jolpica JSON.** Every method
  returns a typed `schemas.py` model — tool functions never parse `MRData.*` nesting
  directly.
- **Name-based race lookup** (`get_race_results_by_name`) resolves a loose name
  ("Monaco", "Monaco GP") against the season's race calendar using substring
  matching first, with a fuzzy fallback (`difflib`) for typos — since the Ergast/
  Jolpica API only supports lookup by round number.
- **Season schedules are cached per-session** to avoid refetching the calendar on
  every name-based lookup.

## Data source

[Jolpica-F1](https://github.com/jolpica/jolpica-f1) — free, no API key required.
Historical race data from 1950 onward; pit stop data from 2011 onward.