carmaker-mcp

# carmaker-mcp

<!-- mcp-name: io.github.De-Ioannidis/carmaker-mcp -->

An [MCP](https://modelcontextprotocol.io) 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](https://github.com/De-Ioannidis/carmaker-mcp/blob/main/docs/verification.md) lists
what has been checked against real software and what has not.

**Contents:** [What it does](#what-it-does) · [What it does not cover](#what-it-does-not-cover) ·
[Requirements](#requirements) · [Setup](#setup) ·
[With the MATLAB MCP server](#using-it-with-the-matlab-mcp-server) · [Settings](#settings) · [Tools](#tools) ·
[Safety and privacy](#safety-and-privacy) · [Troubleshooting](#troubleshooting) ·
[How it works](#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 session | Standalone run |
|---|---|---|
| Use it for | vehicles whose controller is a Simulink model (CarMaker for Simulink) | vehicles with CarMaker's built-in controllers |
| Needs | MATLAB with your model, and the CarMaker GUI (the server can start both) | only CarMaker; no MATLAB, no window |

More worked examples:
[docs/examples.md](https://github.com/De-Ioannidis/carmaker-mcp/blob/main/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](https://github.com/De-Ioannidis/carmaker-mcp/blob/main/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](#1-check-your-machine); only R2024b has been tested)
* [uv](https://docs.astral.sh/uv/) (it fetches the server and its Python environment; pip also works, see
  [docs/setup.md](https://github.com/De-Ioannidis/carmaker-mcp/blob/main/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:

| MATLAB | Python | `uvx` arguments | Bundle on the release page |
|---|---|---|---|
| R2024b | 3.12 | `--python 3.12 --with "matlabengine==24.2.*"` | `...-R2024b-py312.mcpb` |
| R2024a | 3.11 | `--python 3.11 --with "matlabengine==24.1.*"` | `...-R2024a-py311.mcpb` |
| R2023b | 3.11 | `--python 3.11 --with "matlabengine==23.2.*"` | `...-R2023b-py311.mcpb` |
| R2023a | 3.10 | `--python 3.10 --with "matlabengine==9.14.*"` | `...-R2023a-py310.mcpb` |
| R2022b | 3.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
```

<details>
<summary><b>Claude Code</b></summary>

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.

</details>

<details>
<summary><b>Claude Desktop</b></summary>

**One-click bundle.** Download the `.mcpb` file for your MATLAB release from the
[latest release](https://github.com/De-Ioannidis/carmaker-mcp/releases/latest) (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"
      }
    }
  }
}
```

</details>

<details>
<summary><b>GitHub Copilot in Visual Studio Code</b></summary>

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.

</details>

<details>
<summary><b>Codex</b></summary>

Run in a terminal:

```bash
codex mcp add carmaker --env CM_PROJECT="C:\CM_Projects\my-project" --env CM_MODEL