CarMaker

io.github.De-Ioannidisv0.1.1Updated Oct 7, 2026

Drive IPG CarMaker for Simulink: run test runs, read results, edit vehicle data and parameters.

VerifiedSTDIODesktop onlyDeveloper ToolsData & Analytics

Overview

AI-generated overview

Lets an assistant drive IPG CarMaker on Windows: start sessions, run test runs, read results, and edit vehicle and Simulink parameters.

What it does
Connects an AI agent to IPG CarMaker on the same Windows machine. It starts a session (MATLAB, the Simulink model and the CarMaker GUI, or a standalone CarMaker process), loads and runs test runs, waits for them, and reads .erg result files for summaries and time series. It also lists and edits project files, reads and sets MATLAB and Simulink workspace variables and block parameters, runs parameter studies, and keeps a change log with undo and restore.
When to use it
Use it for vehicle-dynamics and controller work in CarMaker, such as running a braking or slalom test run, comparing controller gains, or sweeping a vehicle parameter and tabulating results. It is aimed at standalone runs and CarMaker for Simulink runs; scenario building, Test Manager, HIL, other result formats and remote machines are out of scope.
Requirements
Windows 10 or 11, IPG CarMaker with its Python API, and uv (or pip) to run the PyPI package carmaker-mcp via uvx. MATLAB-connected sessions additionally need CarMaker for Simulink and MATLAB R2022b or newer with the matching matlabengine package. CM_PROJECT (the CarMaker project folder) is required; CM_MODEL, CM_MATLAB_INIT and other CM_ variables are optional. An MCP client is needed.
Before you install
It edits project files and the live Simulink model in place and can start simulations, so connect it only to agents you trust. Files are backed up before the first change and logged, and writes are confined to CM_PROJECT, but result and log files in SimOutput are not removed by a revert. CM_ENABLE turns on raw Tcl and Simulink structure edits; CM_POPUP_TIMEOUT makes CarMaker pop-ups answer themselves with their default, which can discard unsaved GUI changes. It makes no network connections of…

Installation

In SourceWeft

  1. Open CarMaker in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

carmaker-mcp

An MCP server that lets an AI agent drive IPG CarMaker on your computer: start a session, run test runs, read the results, change vehicle data and Simulink controller parameters, and undo what it changed.

Unofficial community project, not affiliated with or endorsed by IPG Automotive or MathWorks. You need your own CarMaker and MATLAB/Simulink licences. This repository contains no IPG or MathWorks code or data.

Status: alpha. Developed and tested on one setup (CarMaker 14.1.1, MATLAB R2024b, Windows 11). docs/verification.md lists what has been checked against real software and what has not.

Contents: What it does · What it does not cover · Requirements · Setup · With the MATLAB MCP server · Settings · Tools · Safety and privacy · Troubleshooting · How it works

What it does

Things you can ask an agent once the server is connected:

  • "Run the braking test run and tell me the stopping distance."
  • "Set Kp_yaw to 1.5 in the controller model, run the slalom again and compare the yaw rate."
  • "Try the lane change with a vehicle mass of 280, 300 and 320 kg and tabulate the lateral acceleration."
  • "The last run aborted. Why?"
  • "Undo everything you changed."

It works in two ways, and the agent picks the one that fits the vehicle:

MATLAB-connected sessionStandalone run
Use it forvehicles whose controller is a Simulink model (CarMaker for Simulink)vehicles with CarMaker's built-in controllers
NeedsMATLAB with your model, and the CarMaker GUI (the server can start both)only CarMaker; no MATLAB, no window

More worked examples: docs/examples.md.

What it does not cover

The server was written for vehicle-dynamics and controller work in a Formula Student team, where every run was either a standalone run or a CarMaker for Simulink run. CarMaker can do much more than that, and the rest is outside what this server does or has been tried with.

Not supported (there are no tools for it):

  • Other platforms and products: Linux; TruckMaker and MotorcycleMaker; CarMaker HIL and CarMaker Office Extended (real-time hardware, Fail Safe Tester, bus interfaces such as CAN, FlexRay, SOME/IP, XCP).
  • CarMaker's own test automation: Test Manager and test series, test reports, parallel (HPC) execution, batch mode with start-up files. The server runs its own parameter studies instead, one run after another.
  • Building scenarios: the Scenario Editor and roads, traffic, sensors, the environment, OpenSCENARIO import. cm_edit changes keys in files that exist; it does not author these things.
  • Most visualisation: Movie NX, IPGControl, Instruments, video export, Model Check. Of IPGMovie, only single pictures.
  • Other result formats: only .erg files are read, not MDF or ASCII.
  • Rebuilding the simulation program: models in C code or generated with Simulink Coder.
  • Remote machines: CarMaker and MATLAB must run on the computer the server runs on.

May work, never tested:

  • FMUs, CarMaker exported as an FMU, third-party tyre models and other co-simulation tools.
  • Encrypted or protected data files.
  • CarMaker and MATLAB versions other than the ones named above; more than one MATLAB session or CarMaker GUI at a time.
  • Several standalone runs in parallel, pausing and resuming a standalone run, parameter studies on standalone runs.
  • Test runs with traffic, sensors or driver-assistance functions. Nothing stands in their way, but every check so far used vehicle-dynamics runs without them.

The state of each tool is in docs/verification.md. Reports from other setups are welcome.

Requirements

  • Windows 10 or 11
  • IPG CarMaker with its Python API (developed on 14.1.1)
  • For the MATLAB-connected session: CarMaker for Simulink and MATLAB R2022b or newer, as far as your CarMaker supports it (see the table in step 1; only R2024b has been tested)
  • uv (it fetches the server and its Python environment; pip also works, see docs/setup.md)
  • An MCP client: Claude Code, Claude Desktop, VS Code with GitHub Copilot, Codex, Antigravity, Cursor, ...

Setup

1. Check your machine

bash
uvx carmaker-mcp doctor

This finds your CarMaker and MATLAB installs, tells you what does not fit and how to fix it, and prints the uvx arguments for your machine. They look like this:

text
uvx --python 3.12 --with matlabengine==24.2.* carmaker-mcp

The two extra arguments matter, which is why the tool works them out for you:

  • --python 3.12 selects a Python version that both your CarMaker and your MATLAB release work with. Without it uvx may pick a newer Python that neither can use.
  • --with "matlabengine==24.2.*" adds the MATLAB engine package for your MATLAB release. Leave it out if you only use standalone runs.

Both depend on the MATLAB release, because MathWorks publishes one engine package per release and each installs only on some Python versions:

MATLABPythonuvx argumentsBundle on the release page
R2024b3.12--python 3.12 --with "matlabengine==24.2.*"...-R2024b-py312.mcpb
R2024a3.11--python 3.11 --with "matlabengine==24.1.*"...-R2024a-py311.mcpb
R2023b3.11--python 3.11 --with "matlabengine==23.2.*"...-R2023b-py311.mcpb
R2023a3.10--python 3.10 --with "matlabengine==9.14.*"...-R2023a-py310.mcpb
R2022b3.10--python 3.10 --with "matlabengine==9.13.*"...-R2022b-py310.mcpb
none (standalone runs only)3.12--python 3.12...-standalone-py312.mcpb

Only the R2024b row has been run against real software. The others follow from the engine packages' published requirements and are untested; reports are welcome. MATLAB R2022a and older cannot be used for the MATLAB-connected session, because their engine packages need a Python older than this server supports (standalone runs still work).

To look at the tools without CarMaker installed: uvx carmaker-mcp --mock.

2. Register the server in your MCP client

Every client needs the same three things: the command uvx, the arguments from step 1, and your settings as environment variables. The settings you will normally set:

  • CM_PROJECT: your CarMaker project folder.
  • CM_MATLAB_INIT: if you normally start work by running a MATLAB script of your project (one that adds folders to the path and opens the model), name it here so that the agent runs it too.
  • CM_MODEL: the Simulink model the agent opens when it starts a session. A name on the MATLAB path, or a path relative to the project's src_cm4sl folder. If you leave it out, the agent is shown the models it finds and picks one or asks you.

Pick your client below. The examples assume MATLAB R2024b and Python 3.12; replace the arguments with the ones doctor printed. Or let the server write the entry for you, with every CM_ variable set in your shell filled in:

bash
uvx carmaker-mcp config --client vscode     # or claude-code, claude-desktop, codex, antigravity, cursor
Claude Code

Run in a terminal:

bash
claude mcp add carmaker --env CM_PROJECT="C:\CM_Projects\my-project" --env CM_MODEL="MyModel" -- uvx --python 3.12 --with "matlabengine==24.2.*" carmaker-mcp

Add further settings with more --env NAME="value" before the --. With --scope project the entry goes into a .mcp.json in the current folder, where you can edit its env block later; otherwise remove and add it again (claude mcp remove carmaker). claude mcp list shows whether the server connects.

Claude Desktop

One-click bundle. Download the .mcpb file for your MATLAB release from the latest release (the table in step 1 names them) and drag it into Settings > Extensions. Fill in the project folder, the model and, if your project has one, its MATLAB setup script in the dialog; Configure changes them later. The bundle holds the server but not its Python environment: Claude Desktop builds that with uv on first use, so uv must be installed.

By hand. Settings > Developer > Edit Config opens claude_desktop_config.json. Add the entry and restart Claude Desktop:

json
{  "mcpServers": {    "carmaker": {      "command": "uvx",      "args": ["--python", "3.12", "--with", "matlabengine==24.2.*", "carmaker-mcp"],      "env": {        "CM_PROJECT": "C:\\CM_Projects\\my-project",        "CM_MODEL": "MyModel"      }    }  }}
GitHub Copilot in Visual Studio Code

Create .vscode/mcp.json in your workspace (for all workspaces: MCP: Open User Configuration in the Command Palette):

json
{  "servers": {    "carmaker": {      "type": "stdio",      "command": "uvx",      "args": ["--python", "3.12", "--with", "matlabengine==24.2.*", "carmaker-mcp"],      "env": {        "CM_PROJECT": "C:\\CM_Projects\\my-project",        "CM_MODEL": "MyModel"      }    }  }}

Click Start above the entry, then use Copilot Chat in agent mode.

Codex

Run in a terminal:

bash
codex mcp add carmaker --env CM_PROJECT="C:\CM_Projects\my-project" --env CM_MODEL="MyModel" -- uvx --python 3.12 --with "matlabengine==24.2.*" carmaker-mcp

or edit C:\Users\<username>\.codex\config.toml:

toml
[mcp_servers.carmaker]command = "uvx"args = ["--python", "3.12", "--with", "matlabengine==24.2.*", "carmaker-mcp"]env_vars = ["WINDIR"]
[mcp_servers.carmaker.env]CM_PROJECT = "C:\\CM_Projects\\my-project"CM_MODEL = "MyModel"

Codex starts servers with a reduced environment; env_vars = ["WINDIR"] passes on a Windows variable that MATLAB's libraries need.

Antigravity

In the agent panel open the ... menu, then MCP Servers > Manage MCP Servers > View raw config. Add the entry to the mcp_config.json that opens, save, and press Refresh in the server list:

json
{  "mcpServers": {    "carmaker": {      "command": "uvx",      "args": ["--python", "3.12", "--with", "matlabengine==24.2.*", "carmaker-mcp"],      "env": {        "CM_PROJECT": "C:\\CM_Projects\\my-project",        "CM_MODEL": "MyModel"      }    }  }}
Cursor and other clients

Cursor: create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects) with the same content as shown for Antigravity. Most other clients use that mcpServers format too.

In JSON and TOML, write Windows paths with double backslashes or with forward slashes. So far only Claude Code has been used with this server; the other entries follow each client's documented format.

3. Start a session

Ask the agent, for example "start CarMaker and run the braking test run". It opens MATLAB, your model and the CarMaker GUI as far as they are not open yet, and never closes anything.

If you would rather open MATLAB and CarMaker yourself, run this once per MATLAB session (or put it into startup.m) so that the server can attach:

matlab
matlab.engine.shareEngine('cm_mcp')

Standalone runs need neither.

Using it with the MATLAB MCP server

For CarMaker for Simulink work it is worth connecting MathWorks' MATLAB MCP Core Server as well. It is optional, and standalone runs do not need it. The two servers do different jobs:

ServerUse it for
carmaker-mcpThe CarMaker side: session, test runs, run control, results and project data, and controller parameters with a change log and undo
MATLAB MCP serverThe MATLAB side: writing, checking and running MATLAB code (post-processing scripts, plots) and looking into the Simulink model

Things to know when you use both:

  • Let both work on the same MATLAB session (set the MATLAB server up to use your open MATLAB, see its README), so that they see the same model and workspace. This is how the pair was used during development.
  • MATLAB does one thing at a time. While a model compiles or a simulation runs, calls through the MATLAB server wait. This server's run tools are built around that (time-limited waits that are simply repeated).
  • Start and stop runs with this server's tools, so that it can follow the run (result file, errors, storage mode).
  • What is changed through the MATLAB server is not in this server's change log, and cm_revert_all does not undo it.

Settings

All settings are environment variables in the client entry, set like CM_PROJECT and CM_MODEL above.

Common

VariableDefaultMeaning
CM_PROJECTread from the running CarMaker GUICarMaker project folder. The server writes nowhere else. Needed to start a session from scratch
CM_MODELnoneSimulink model to open when a session is started
CM_MATLAB_INITnoneYour project's own MATLAB setup script (in src_cm4sl, or a full path), run once when a session is started. Use it if you normally run a script that adds folders to the path and opens the model: without it the model may not compile
CM_POPUP_TIMEOUTnot setSeconds after which CarMaker pop-ups answer themselves with their default choice, so that a question cannot block a run. Not set: they wait for your click. See Safety
CM_DISABLEnoneTool groups to switch off, to give the model a shorter tool list: standalone, study, matlab, movie
CM_ENABLEnoneOptional tools to switch on: tcl (raw Tcl in the CarMaker GUI), experimental (add and delete Simulink blocks)

Advanced

VariableDefaultMeaning
CM_HOMEnewest C:\IPG\carmaker\win64-*CarMaker install folder
CM_MATLAB_EXEnewest installed MATLAB that your CarMaker supportsMATLAB executable used to start a session
CM_MATLAB_DIR<project>/src_cm4slFolder MATLAB starts in (where cmenv.m is)
CM_MATLAB_SESSIONcm_mcpName under which MATLAB shares its engine
CM_RESULT_DIRSnoneExtra folders to search for result files
CM_STATE_DIR%LOCALAPPDATA%\carmaker-mcpWhere backups, the change log and server.log are kept (never inside the project)
CM_ENGINE_TIMEOUT30Seconds before a call into MATLAB is given up
CM_LOG_LEVELINFODetail of server.log

Tools

Each tool tells the client whether it is read-only, changes state, or is destructive, so that clients can ask for confirmation where it matters. Every parameter is described in docs/tools.md.

Session and runs

ToolWhat it does
cm_session_startStart MATLAB, the model and the CarMaker GUI as far as they are missing
cm_doctorCheck the setup and say how to fix what is wrong
cm_statusSimulation state, active model, project folder
cm_load_testrunLoad a test run into the CarMaker GUI
cm_start_sim, cm_stop_simStart and stop the simulation; a run writes a result file by default
cm_wait_endWait for the end of the run; returns end status, simulation time, distance and the result file
cm_liveRead quantities while the simulation runs
cm_dva_write, cm_dva_releaseOverwrite a quantity during a run (Direct Variable Access)
cm_logRead CarMaker's session log, for example after an aborted run
cm_popups, cm_popup_timeoutSee what the CarMaker GUI asked or reported, and let pop-ups answer themselves

Results

ToolWhat it does
cm_results_listNewest result files
cm_results_summaryFirst, last, min, max and mean of quantities in a result file; search for quantity names
cm_results_readTime series from a result file
cm_output_quantities, cm_output_quantities_editSee which quantities runs write to result files, and add or remove some
cm_movie_open, cm_movie_snapshotOpen IPGMovie and get a picture of the 3D view: any moment of the last run, or of a result file

Project data and parameters

ToolWhat it does
cm_list, cm_readList and read test runs, vehicles, drivers, tyres and other project files
cm_edit, cm_cloneChange keys in a project file (only the edited lines change), or copy a file
cm_list_workspace_vars, cm_get_workspace_var, cm_set_workspace_varMATLAB base workspace and Simulink model workspace, where controller parameters usually are
cm_model_get, cm_model_set, cm_model_saveSimulink block and model parameters; save the model
cm_model_logs_saveAfter a run, save what Simulink logged (logged signals, To Workspace blocks) and both workspaces to a MAT file. save_logs on cm_start_sim and cm_study_start does it automatically for every run
cm_study_start, cm_study_status, cm_study_cancelRun one test run with several parameter sets and tabulate the results, without changing any file

Standalone runs (no MATLAB)

ToolWhat it does
cm_standalone_launchStart an independent CarMaker process and run a test run on it
cm_standalone_status, cm_standalone_wait_end, cm_standalone_resultsFollow the run and get its result files
cm_standalone_control, cm_standalone_dva_writePause, resume or stop; overwrite a quantity
cm_standalone_servers, cm_standalone_attachFind and attach to CarMaker programs that are already running
cm_standalone_closeStop the process

History

ToolWhat it does
cm_changelogWhat this session changed, with old and new values
cm_revert_allUndo this session's changes
cm_restoreRestore the files of an earlier session from its backups

The server also provides resources (carmaker://guide, carmaker://status, carmaker://changelog, carmaker://log) and three prompts (run_and_summarise, compare_settings, undo_session).

Safety and privacy

This server can start simulations and edit your project files and the live Simulink model in place. Connect it only to agents you trust.

What protects your work:

  • Every file is backed up before its first change, every change is logged with its old value, and cm_revert_all undoes a session.
  • Files are only written inside the project folder, and only while the simulation is idle. No tool deletes project files.
  • Raw Tcl and Simulink structure edits are off unless you switch them on with CM_ENABLE.
  • CarMaker pop-ups wait for your click by default. If you set CM_POPUP_TIMEOUT, a question such as "Vehicle not saved. All changes will be lost. OK to continue?" is answered with its default, which discards unsaved changes in the CarMaker GUI.

Runs write result and log files into the project's SimOutput folder; a revert does not remove those.

The server collects no telemetry and makes no network connections of its own. It only talks to MATLAB and CarMaker on your machine. Details: docs/safety.md.

Troubleshooting

Run uvx carmaker-mcp doctor first: it names most setup problems together with their fix.

SymptomCause and fix
"No shared MATLAB session"MATLAB is closed or has not shared its engine. Let the agent start the session, or run matlab.engine.shareEngine('cm_mcp') in MATLAB
uvx fails while installing matlabengineThe pin must match your MATLAB release, and that MATLAB must be installed. Use the arguments doctor prints
"CarMaker ships no cmapi for Python 3.x"Add --python 3.12 (or another version the message lists)
A tool call hangs at load or startThe CarMaker GUI is showing a question. Answer it, or see CM_POPUP_TIMEOUT
"too many licenses in use" on a standalone runAn open MATLAB with CarMaker for Simulink holds the licence. Close that model or MATLAB
The wait tool returns finished: falseNot an error: waits are limited to 45 s per call and are simply repeated

More: docs/troubleshooting.md. The server's own log is server.log in the state folder.

How it works

  • MATLAB-connected session: the server attaches to your MATLAB through the MATLAB Engine for Python and sends commands to the CarMaker GUI through CarMaker for Simulink's own cmguicmd (the GUI's Tcl / ScriptControl interface).
  • Standalone runs: it uses IPG's Python API cmapi, loaded from your CarMaker install, to start and control a separate CarMaker process.
  • Project files are edited by a byte-preserving editor for CarMaker's infofile format, and results are read by a NumPy reader for .erg files (checked against MATLAB's cmread).

Nothing of IPG's or MathWorks' is bundled or redistributed.

Documentation and contributing

Related work: pycarmaker talks to the command port of a standalone CarMaker program. This project also covers CarMaker for Simulink, uses IPG's own interfaces, and shares no code with it.

Licence

MIT, see LICENSE.

Source: README.md at commit 357af1d

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.1.1LatestOct 7, 2026