ac-race-engineer

MCP server that turns Claude into a race engineer for original Assetto Corsa. It reads AC's shared memory telemetry, stores laps in SQLite, reduces them to engineer-grade summaries, and can read/write setup files that appear directly in the in-game setup menu.

Runs on the Windows machine running Assetto Corsa. Original AC only (uses the acpmf_* shared memory layout, not ACC's).

Install (Windows — the easy way)

Prerequisite: Python 3.10+ from python.org. On the installer's first screen tick "Add python.exe to PATH". Don't use the Microsoft Store build — its sandboxing breaks shared-memory access.

Then, in this folder: right-click install-windows.bat → Open (or just double-click it).

That's it. The installer finds Python, installs the package, writes the Claude Desktop config (merging with any MCP servers you already have, and taking a backup first), locates your Assetto Corsa install, and copies the in-game Lua app into place. Re-run it any time after a git pull; it updates in place.

If it can't find Assetto Corsa, tell it where to look. Flags go on the .bat, not the .ps1 — Windows blocks .ps1 files from running directly under the default execution policy, and the .bat exists to work around exactly that:

install-windows.bat -AcPath "D:\Games\steamapps\common\assettocorsa"

Other flags: -SkipLuaApp, -Uninstall.

After installing, fully quit Claude Desktop and reopen it. Closing the window isn't enough — right-click the Claude icon in the system tray (bottom right, possibly hidden under the ^ arrow) and choose Quit.

Related MCP server: fastf1-mcp-server

Install (manual)

python -m pip install -e .

Then add the server to claude_desktop_config.json. The fastest way to open that file is Claude Desktop → Settings → Developer → Edit Config, which creates it if missing and opens the containing folder — no filesystem archaeology required.

%APPDATA% is an environment variable, not a literal path. It expands to C:\Users\<you>\AppData\Roaming — and AppData is a hidden folder, so browsing to it in Explorer shows nothing unless you enable View → Hidden items.

The bigger gotcha: %VAR% is cmd.exe syntax. Windows Terminal defaults to PowerShell, where the same variable is spelled $env:VAR. So:

To open the folder rather than the file, use explorer $env:APPDATA\Claude in PowerShell.

{
  "mcpServers": {
    "ac-race-engineer": {
      "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
      "args": ["-m", "ac_race_engineer.server"]
    }
  }
}

Use the absolute path to python.exe, not bare "python". Claude Desktop launches MCP servers without your shell's PATH, so a bare command frequently fails silently. Get the correct path with:

py -c "import sys; print(sys.executable)"

Don't use (Get-Command python).Source — on stock Windows that often returns ...\WindowsApps\python.exe, the Microsoft Store alias stub, which is the wrong answer. Remember JSON needs backslashes doubled (\\).

(If you use Claude Code instead: claude mcp add ac-race-engineer -- python -m ac_race_engineer.server)

Optional environment overrides:

• AC_DOCS_DIR — AC documents folder (default ~/Documents/Assetto Corsa)

• AC_ENGINEER_DATA — DB + ranges location (default ~/.ac-race-engineer)

• AC_ENGINEER_BRIDGE_PORT — in-game app bridge port (default 9666)

Troubleshooting

Claude doesn't list the tools. Confirm you fully quit and reopened Claude Desktop (tray icon → Quit). Then read the server log:

notepad $env:APPDATA\Claude\logs\mcp-server-ac-race-engineer.log

Typing python opens the Microsoft Store (or says "not recognized"). Windows ships an app-execution-alias stub at %LOCALAPPDATA%\Microsoft\WindowsApps\python.exe that hijacks the name when no real Python is on PATH. Install Python from python.org with "Add python.exe to PATH" ticked, or use the py launcher (py -3 -m pip install -e .) — the python.org installer sets that up by default. You can also kill the stub in Settings → Apps → Advanced app settings → App execution aliases.

The installer already ignores anything under WindowsApps, so this only bites you on a manual install.

.ps1 cannot be loaded because running scripts is disabled. That's the execution policy. Use install-windows.bat instead — it bypasses the policy for that one script without changing any system setting.

Setup values don't stick in-game. You're writing outside the car's legal range and AC is silently ignoring them — see the next section.

The tuning loop

1. Start AC, get on track.

2. Tell Claude: "start recording and confirm you can see the session" (start_recording, live_snapshot).

3. Drive 3–5 laps. Laps store automatically as they complete; off-track excursions (>2 tyres out) mark a lap invalid.

4. "Summarize my last lap and read my current setup" (list_laps, lap_summary, read_setup). The summary includes per-corner min speed, brake points, tyre pressures/temps, and a slip-balance metric (positive = understeer, negative = oversteer).

5. Discuss what the car is doing; Claude writes a revised setup with write_setup (e.g. as claude_v1).

6. Pit, load claude_v1 from the setup screen, drive again.

7. "Compare my best lap on the new setup against lap N" (compare_laps) — corner-by-corner min speed and brake point deltas show whether the change actually worked.

Setup value clamping (recommended)

AC silently ignores setup values outside the ranges defined in the car's setup.ini (inside data.acd). To let the server clamp and snap values to each car's legal min/max/step:

1. In Content Manager: car page → unpack data (or use QuickBMS).

2. Copy the car's setup.ini into the ranges folder, named after the car's folder name — e.g. ks_mazda_mx5_cup.ini.

To open that folder (the installer already created it):

explorer $env:USERPROFILE\.ac-race-engineer\ranges

(cmd.exe: explorer %USERPROFILE%\.ac-race-engineer\ranges)

Without a ranges file, writes still work but come back with a warning, and you should sanity-check the values in the setup screen.

In-game app (CSP Lua)

install-windows.bat copies this in for you. To do it by hand, copy lua_app/race_engineer/ to assettocorsa/apps/lua/race_engineer/ (requires Custom Shaders Patch; you already have it if you use Content Manager with CSP enabled). Enable it from the in-game apps sidebar — move the mouse to the right edge of the screen while in a session.

Not sure where Assetto Corsa is installed? In Steam, right-click Assetto Corsa → Manage → Browse local files.

What it does:

• Complaint tags while driving — Understeer / Oversteer / Braking / Traction buttons, each bindable to a wheel button via the app's Settings window (they show up as CSP control bindings). Pressing one records your exact spline position, lap, and speed. Claude reads them with get_driver_notes and correlates them with corner telemetry: "you flagged understeer twice at spline 0.34 — that's the corner where front slip exceeds rear by 0.09".

• Status overlay — recording indicator + laps stored, so you never alt-tab to check.

• Messages from Claude — send_driver_message puts a note on the overlay ("claude_v2 saved — pit and load it"); dismiss with OK.

The app talks to the server's HTTP bridge on 127.0.0.1:9666 (change with AC_ENGINEER_BRIDGE_PORT, and edit BASE in the Lua to match). The bridge binds localhost only.

Layout

ac_race_engineer/
  sim_info.py   shared memory structs (physics / graphics / static)
  collector.py  background sampler -> SQLite, lap boundary detection
  db.py         schema + storage
  analysis.py   corner detection, lap summaries, lap comparison
  setups.py     setup INI read/write, range clamping
  bridge.py     localhost HTTP bridge for the in-game app
  server.py     MCP tools
lua_app/
  race_engineer/  CSP Lua in-game app (copy to apps/lua/)
install-windows.ps1  one-shot Windows installer
install-windows.bat  double-clickable wrapper for the above

Notes / future ideas

• Sampling is 25Hz — plenty for setup work while keeping the DB tiny. Bump TARGET_HZ in collector.py if you want finer traces.

• Out-laps (no valid time) are skipped automatically.

• Corner detection is generic (speed minima); a per-track corner-name map would make Claude's advice read nicer ("T3/Variante" vs "corner at 0.34").

• CSP/Lua could expose damper velocities and more channels than stock shared memory if you ever want deeper suspension work — Telemetrick's source is a good reference.