# fh5-mcp

An MCP server that sits in front of my [FH5 Telemetry](https://github.com/bebulli/fh5-telemetry) Java app, so an AI assistant can answer questions about my Forza Horizon 5 driving sessions in plain English instead of me clicking around a web UI.

This was mostly a "learn what MCP actually is" project. It's a thin wrapper, all it does is call the Java app's REST API and hand the result back in a shape a model can use. No telemetry parsing or tuning logic lives here, that's all still in the Java app.

## What it does

Four tools:

- `list_sessions` - lists recorded sessions
- `get_session_summary(session_id)` - duration, top speed, peak power, PI, drivetrain for one session
- `get_telemetry_window(session_id, start_ms, end_ms)` - telemetry samples for a time slice, capped at 100 samples so it doesn't dump a whole session into the model's context
- `get_tuning_recommendation(session_id, weight_kg, ...)` - runs the Java app's tuning engine against a session

## Example

Something like "what was my top speed in my last session and does the tuning engine have any suggestions" would go:

1. `list_sessions` to find the most recent recording
2. `get_session_summary` on it, that's where top speed comes from
3. `get_tuning_recommendation` with a weight (has to be supplied, Forza never sends car weight over telemetry), drivetrain/power/PI get pulled from the session automatically if you don't pass them

If you also said "it kept understeering," the model would pass `symptoms=["understeer"]` to the last call and the recommendation adjusts for it.

## Running it locally

Needs the Java app running first (`http://localhost:7070` by default, see that repo for how to start it).

```
python -m venv .venv
.venv\Scripts\pip install -e ".[dev]"
.venv\Scripts\python -m fh5_mcp.server
```

That starts it over stdio, which is how an MCP client is meant to talk to it (the client launches it, not the other way around), so running it standalone like this is mostly just for checking it starts without errors.

Run the tests with:

```
.venv\Scripts\python -m pytest -v
```

They mock the Java API, so the Java app doesn't need to be running for these.

## Running in Docker

Build it:

```
docker build -t fh5-mcp .
```

Run it over stdio (this is what you'd point an MCP client at):

```
docker run -i --rm fh5-mcp
```

Or bring it up as an HTTP service with docker-compose, which also points it at a Java app running on your host machine:

```
docker compose up
```

That runs the server on `http://localhost:8080/mcp`. Compose sets `MCP_TRANSPORT=streamable-http` for this, since a persistent container is a better fit for HTTP than stdio, stdio is meant to be spawned per client session, not left running in the background.

## Config

Two env vars if you need to change anything:

- `FH5_JAVA_API_BASE` - where the Java app is, defaults to `http://localhost:7070`
- `MCP_TRANSPORT` - `stdio` (default) or `streamable-http`

## Connecting an MCP client

For something like Claude Desktop, point it at the local venv:

```json
{
  "mcpServers": {
    "fh5-telemetry": {
      "command": "C:/path/to/FH5_TELEMETRY_MCP/.venv/Scripts/python.exe",
      "args": ["-m", "fh5_mcp.server"]
    }
  }
}
```

or at the Docker image instead, so you don't need a local Python setup at all:

```json
{
  "mcpServers": {
    "fh5-telemetry": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "fh5-mcp"]
    }
  }
}
```

Either way, make sure the Java app is running and reachable first, otherwise every tool call comes back with a "can't reach the telemetry service" error instead of data.