fh5-mcp

An MCP server that sits in front of my 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:

{
  "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:

{
  "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.