Skip to main content
Glama

assetto-corsa-mcp

An MCP server plus a small Custom Shaders Patch (CSP) Lua app that let an MCP client (Claude Code, Claude Desktop, or any other MCP client) control Assetto Corsa: start an offline practice session, fly a free camera to exact world coordinates, set the time of day and the date, take screenshots, read the camera and car state, and quit again. Every config file it changes is backed up first and restored afterwards.

It was written to check track and building work in game ("go to x/y/z at 19:00 on 15 December and take a picture"), but the tools are generic and work on any track.

MCP client  --stdio-->  ac_mcp.server (Python)  --JSON files-->  claude_bridge (CSP Lua app inside AC)
                              |                                         |
                              +-- writes race.ini, starts acs.exe        +-- camera, time, screenshots, state

Requirements

  • Windows, Assetto Corsa (Steam, app 244210).

  • Custom Shaders Patch with Lua apps. Tested with CSP 0.3.0-preview581 (build 4116). The app only uses functions present in that SDK (extension/internal/lua-sdk/ac_apps/lib.lua). Older 0.2.x builds may lack some of them (ac.setWeatherExactUTC0Timestamp, ac.makeScreenshot with a path, ac.grabCamera), so they are untested.

  • Python 3.10 or newer (tested with 3.13) and the mcp package (tested with mcp 2.3.0; the 1.x FastMCP import is used as a fallback).

  • Content Manager is not required. ac_launch writes race.ini itself and starts acs.exe directly; Steam must be running.

Related MCP server: warudo-agent-bridge

Install

git clone <this repo> assetto-corsa-mcp
cd assetto-corsa-mcp
py -3 -m venv .venv
.venv\Scripts\python -m pip install -e .
powershell -ExecutionPolicy Bypass -File scripts\install_lua_app.ps1

The last step copies lua/claude_bridge/ to <AC>\apps\lua\claude_bridge\. Run it again after updating the repository. CSP reloads the app on file change, so this also works while AC is running.

Configuration

what

how

AC game folder

AC_ROOT environment variable, else auto-detected from Steam (registry SteamPath plus steamapps\libraryfolders.vdf)

Documents\Assetto Corsa

AC_DOCUMENTS environment variable, else the Windows Documents folder

install script

-AcRoot <path>, else AC_ROOT, else Steam detection

The bridge exchanges files in Documents\Assetto Corsa\claude_bridge\:

  • cmd.json: the command

  • result.json: the answer

  • status.json: a heartbeat, written about once per second while a session runs

  • backups\: config backups plus pending_restore.json

MCP client setup

Claude Code, from your project folder:

claude mcp add assetto-corsa -- "C:\path\to\assetto-corsa-mcp\.venv\Scripts\python.exe" -m ac_mcp.server

or add it to the project's .mcp.json:

{
  "mcpServers": {
    "assetto-corsa": {
      "type": "stdio",
      "command": "C:\\path\\to\\assetto-corsa-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "ac_mcp.server"],
      "env": {}
    }
  }
}

Claude Desktop: add the same mcpServers entry (without "type") to %APPDATA%\Claude\claude_desktop_config.json and restart Claude Desktop. Restart Claude Code or start a new session after changing .mcp.json.

Tools

tool

arguments

what it does

ac_launch

track, car="abarth500", layout="", skin="", hour=13, window_width=0, window_height=0, start_session=true, timeout=240

Backs up race.ini and writes an offline practice session. With a window size, it also backs up video.ini and switches to a single windowed screen. Starts acs.exe, waits for the bridge heartbeat, then presses Drive.

ac_status

Reports whether acs.exe is running, whether the bridge is alive (session loaded), the last heartbeat, and any pending config restores.

ac_get_state

Live state: camera mode, position, look direction and FOV; car position and speed; time, timestamp and day of year; fps.

ac_camera_free

x, y, z, yaw=0, pitch=0, fov=0

Holds the camera at a world position (ac.grabCamera).

ac_camera_look_at

pos[3], target[3], fov=0

Holds the camera at pos, looking at target.

ac_camera_mode

mode

Releases the camera and switches mode: free (F7), cockpit, chase, chase2, bonnet, car (F6), track, or release.

ac_set_time

hour, minute=0, day=0, month=0, year=0, freeze=true

Sets the track-local time and date with ac.setWeatherExactUTC0Timestamp (offline only); 0 keeps the current date.

ac_screenshot

path, hide_apps=true

Saves via ac.makeScreenshot (PNG, JPG or BMP by extension). Falls back to a PowerShell capture of the AC window.

ac_teleport_car

x, y, z, yaw=-1

Moves the player car (physics.setCarPosition) and reports whether it moved. Works offline.

ac_material_get

filter, properties

Reads material values at runtime. filter is a CSP mesh filter such as material:MyMat.

ac_material_set

filter, property, value[]

Overrides a material value at runtime only; nothing is written to disk.

ac_track_config

pattern, values, limit

Returns track CSP config sections as CSP parsed them, with INCLUDEs merged. Use it to check that an included INI was really loaded.

ac_quit

restore_configs=true

Asks AC to shut down through the bridge, uses taskkill only if it hangs, then restores the backed-up configs.

ac_restore_configs

Restores leftover backups, for example after a crash. Only works while AC is not running.

ac_blender_to_ac

x, y, z

Converts Blender coordinates to AC coordinates.

The same functions can be used without MCP from Python (ac_mcp.api, ac_mcp.launcher, ac_mcp.bridge); see tests/smoke_test.py and examples/.

Coordinates

  • AC world coordinates have Y up.

  • yaw is in degrees: 0 looks along −Z, 90 along +X, 180 along +Z, 270 along −X.

  • pitch is in degrees, positive looks up.

  • fov is the vertical field of view in degrees.

  • From Blender (FBX/ksEditor export with default axes): AC x = Blender x, AC y = Blender z, AC z = −Blender y. On a north-up model, yaw 0 looks north.

Limits

  • Offline sessions only. Time, teleport and launch do not work online; the app refuses nothing, but CSP ignores those calls online.

  • freeze=true calls ac.setWeatherTimeMultiplier(0). With some weather controllers (tested: Pure, "static" controller) time keeps running at 1×, so set the time right before each batch of shots.

  • The track's timezone is measured and corrected automatically: set_time reads sim.timestamp back and corrects the difference. Tracks without coordinates use longitude 0 / UTC, so sunset times are not those of the real place.

  • Time changes and loading need a few seconds to settle (lighting conditions have lag). Wait 3 to 6 s before taking a screenshot.

  • ac_launch always starts a one-car practice session in the pits. Content Manager presets, AI and online are not supported.

  • The PowerShell screenshot fallback needs a windowed or borderless AC window visible on screen.

  • Triple-screen setups render three views; use window_width/window_height for a single-screen session.

  • While the bridge holds the camera, or has handled a command in the last 10 s, it shows a small "Claude bridge active" label in the top-left corner. The label is hidden during screenshots. Otherwise the app does nothing.

Troubleshooting

  • Is the bridge alive? Call ac_status. bridgeAlive is true when status.json is younger than 5 s. The app only runs once a session has loaded.

  • CSP log: Documents\Assetto Corsa\logs\custom_shaders_patch.log. Search for Claude Bridge: there should be a line Lua: <App: Claude Bridge> loaded and ready to run. Screenshots show up as Screenshot requested from Lua API.

  • Configs not restored after a crash: call ac_restore_configs with AC closed. The originals are also in Documents\Assetto Corsa\claude_bridge\backups\*.orig.

  • AC exits during loading: see Documents\Assetto Corsa\logs\log.txt. A missing car or track is reported by ac_launch before it starts AC.

  • Nothing happens on commands: make sure the app folder is apps\lua\claude_bridge and that CSP's Lua apps are enabled. The app appears as "Claude Bridge" in the in-game app list.

Uninstall

  1. powershell -ExecutionPolicy Bypass -File scripts\install_lua_app.ps1 -Uninstall. This removes <AC>\apps\lua\claude_bridge\.

  2. Delete Documents\Assetto Corsa\claude_bridge\ (channel files and config backups). Check first that backups\pending_restore.json does not exist, or run ac_restore_configs before deleting.

  3. Remove the assetto-corsa entry from your .mcp.json / claude_desktop_config.json, or run claude mcp remove assetto-corsa.

  4. Delete this folder, including .venv.

License

MIT. See LICENSE.

Available Tools

15 tools
ac_blender_to_acA

Convert Blender coordinates to AC world coordinates (AC x = Bx, AC y = Bz, AC z = -By).

Inputs: x (required), y (required), z (required). Returns: result

ac_camera_freeB

Hold the camera at AC world position (x, y, z). yaw deg: 0 = look along -Z, 90 = +X, 180 = +Z, 270 = -X. pitch deg: + up, - down. fov: vertical FOV in degrees (0 = keep).

Inputs: x (required), y (required), z (required), fov, +2 more.

ac_camera_look_atC

Hold the camera at pos [x, y, z] looking at target [x, y, z] (AC world coordinates).

Inputs: pos (required), target (required), fov.

ac_camera_modeA

Release the held camera and switch AC camera: 'free' (F7), 'cockpit', 'chase', 'chase2', 'bonnet', 'car' (F6), 'track' (replay cams), or 'release' (only let go of the held camera).

Inputs: mode (required).

ac_get_stateB

Live state from the bridge: camera mode/position/look/fov, car position/speed, time and day of year, fps.

Inputs: no named parameters.

ac_launchA

Start an offline practice session (writes a temporary race.ini after backing it up, starts acs.exe, waits for the bridge heartbeat, presses Drive). window_width/height > 0 temporarily switches video.ini to a single windowed screen of that size (restored by ac_quit). hour is the start time (08..18); use ac_set_time for any time/date.

Inputs: track (required), car, hour, skin, +5 more.

ac_material_getA

Read material properties at runtime (first mesh matching a CSP mesh filter, e.g. 'material:MyMat'). Default properties: ksEmissive, ksAmbient, ksDiffuse, ksAlphaRef.

Inputs: filter (required), properties.

ac_material_setB

Override a material property at runtime only (lost on restart; nothing is written to disk). value: 1-4 numbers, e.g. [1, 0.8, 0.5] for ksEmissive.

Inputs: value (required), filter (required), property (required).

ac_quitA

Quit AC (bridge shutdown first, taskkill only if it hangs) and restore race.ini/video.ini backups.

Inputs: restore_configs.

ac_restore_configsA

Restore any configs still backed up by ac_launch (e.g. after a crash). Only when AC is not running.

Inputs: no named parameters.

ac_screenshotA

Save a screenshot (PNG/JPG by extension) to path via CSP ac.makeScreenshot; falls back to a PowerShell capture of the AC window. Returns the path and the method used.

Inputs: path (required), hide_apps.

ac_set_timeB

Set track-local time and (optionally) date via ac.setWeatherExactUTC0Timestamp (offline only). day/month/year 0 = keep the current date. freeze=True sets the time multiplier to 0.

Inputs: hour (required), day, year, month, +2 more.

ac_statusB

Is acs.exe running, is the bridge alive (session loaded), plus the last heartbeat (camera, time, car).

Inputs: no named parameters.

ac_teleport_carA

Move the player car (physics.setCarPosition; aligned on the track surface). yaw < 0 aligns to the AI spline. Reports whether the car actually moved.

Inputs: x (required), y (required), z (required), yaw.

ac_track_configB

Sections of the track's CSP config as CSP parsed it (INCLUDEs merged), filtered by a Lua pattern on the section name (e.g. '^MATERIAL_ADJUSTMENT'). Useful to check whether an included INI was really loaded.

Inputs: limit, values, pattern.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have distinct purposes: camera control is split cleanly into mode/free/look_at, and launch/quit/restore are clearly separated. The main overlap is between ac_get_state and ac_status, which both surface camera/car/time heartbeat data, though status adds process/bridge health.

    Naming Consistency4/5

    All names use a consistent ac_ prefix and snake_case, which is easy to scan. Minor deviations exist in ordering, mixing verb-first (ac_get_state, ac_set_time) with noun-first (ac_camera_mode, ac_material_get), but the pattern remains readable.

    Tool Count5/5

    At 15 tools the set is well-scoped for a game-control bridge, with each tool covering a distinct capability (camera, time, materials, lifecycle). No obvious filler tools.

    Completeness4/5

    The surface covers the full session lifecycle (launch, status, state, quit, restore configs) plus camera, time, screenshot, teleport, materials, and track config. Gaps exist around car input control (throttle/brake/steering) and replay manipulation, but core automation workflows are covered.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables an MCP client to connect to a running Blockland client to execute TorqueScript, inspect player state, control character movement and actions, and capture screenshots.
      MIT
    • A
      license
      D
      quality
      C
      maintenance
      Enables AI clients to control and inspect a Unity Editor through MCP tools for scene and play-mode operations, logs, screenshots, assertions, Lua execution, UI interaction, world observation, and bridge management; advanced UI/Lua/world features require project-specific adapters.
      41
      MIT