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:

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 a MATLAB release your CarMaker supports
• 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

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:

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 your CarMaker ships its Python API for (CarMaker 14.1: up to 3.12). Without it uvx may pick a newer Python that CarMaker cannot work with.
• --with "matlabengine==24.2.*" adds the MATLAB engine package for your MATLAB release (R2023b 23.2.*, R2024a 24.1.*, R2024b 24.2.*, R2025a 25.1.*). Leave it out if you only use standalone runs.

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 two 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:

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

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

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

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

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

[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"

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

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.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:

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

Advanced

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

Results

Project data and parameters

Standalone runs (no MATLAB)

History

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.

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

• Setup in detail (pip, updating, the single-file executable)
• Example sessions
• Tools reference
• What is verified
• Contributing: test reports from other CarMaker and MATLAB versions are especially welcome
• Security policy

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.