assetto-corsa-mcp
Provides coordinate conversion from Blender's axes (as exported via FBX/ksEditor) to Assetto Corsa world coordinates, so positions authored in Blender can be translated into in-game camera or car positions and orientations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@assetto-corsa-mcp launch a practice session at Spa at 19:00 and take a screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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, stateRequirements
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.makeScreenshotwith a path,ac.grabCamera), so they are untested.Python 3.10 or newer (tested with 3.13) and the
mcppackage (tested with mcp 2.3.0; the 1.xFastMCPimport is used as a fallback).Content Manager is not required.
ac_launchwritesrace.iniitself and startsacs.exedirectly; 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.ps1The 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 |
|
|
|
install script |
|
The bridge exchanges files in Documents\Assetto Corsa\claude_bridge\:
cmd.json: the commandresult.json: the answerstatus.json: a heartbeat, written about once per second while a session runsbackups\: config backups pluspending_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.serveror 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 |
|
| Backs up |
| Reports whether | |
| Live state: camera mode, position, look direction and FOV; car position and speed; time, timestamp and day of year; fps. | |
|
| Holds the camera at a world position ( |
|
| Holds the camera at |
|
| Releases the camera and switches mode: |
|
| Sets the track-local time and date with |
|
| Saves via |
|
| Moves the player car ( |
|
| Reads material values at runtime. |
|
| Overrides a material value at runtime only; nothing is written to disk. |
|
| Returns track CSP config sections as CSP parsed them, with INCLUDEs merged. Use it to check that an included INI was really loaded. |
|
| Asks AC to shut down through the bridge, uses |
| Restores leftover backups, for example after a crash. Only works while AC is not running. | |
|
| 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=truecallsac.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_timereadssim.timestampback 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_launchalways 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_heightfor 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.bridgeAliveis true whenstatus.jsonis younger than 5 s. The app only runs once a session has loaded.CSP log:
Documents\Assetto Corsa\logs\custom_shaders_patch.log. Search forClaude Bridge: there should be a lineLua: <App: Claude Bridge> loaded and ready to run. Screenshots show up asScreenshot requested from Lua API.Configs not restored after a crash: call
ac_restore_configswith AC closed. The originals are also inDocuments\Assetto Corsa\claude_bridge\backups\*.orig.AC exits during loading: see
Documents\Assetto Corsa\logs\log.txt. A missing car or track is reported byac_launchbefore it starts AC.Nothing happens on commands: make sure the app folder is
apps\lua\claude_bridgeand that CSP's Lua apps are enabled. The app appears as "Claude Bridge" in the in-game app list.
Uninstall
powershell -ExecutionPolicy Bypass -File scripts\install_lua_app.ps1 -Uninstall. This removes<AC>\apps\lua\claude_bridge\.Delete
Documents\Assetto Corsa\claude_bridge\(channel files and config backups). Check first thatbackups\pending_restore.jsondoes not exist, or runac_restore_configsbefore deleting.Remove the
assetto-corsaentry from your.mcp.json/claude_desktop_config.json, or runclaude mcp remove assetto-corsa.Delete this folder, including
.venv.
License
MIT. See LICENSE.
Available Tools
15 toolsac_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
Scored across 15 tools
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.
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.
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.
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
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Unofficial Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Remote MCP server for AI.TV creators — delegate account operations to your AI agent over MCP.
Related MCP Servers
- AlicenseBqualityDmaintenanceA local, safety-gated MCP server for controlling, inspecting, extending, and testing BeamNG simulations, combining BeamNGpy with a Lua WebSocket extension and real-time perception/control.572MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to inspect and control a running WARUDO scene, including assets, character pose and IK, expressions, blueprints, camera, and captures, through an MCP client.16 npm10MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseDqualityCmaintenanceEnables 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.41MIT