CarSim MCP — a Claude Code plugin
Drive CarSim (test in version 2024) from Claude Code (or any MCP client): edit parameters, run the
headless solver, and run CarSim ↔ MATLAB/Simulink co-simulation (both .m
controllers and .slx models). It ships as a Claude Code plugin with a bundled
MCP server.
CarSim-domain work lives in this server; MATLAB execution is delegated to the official MATLAB MCP (a warm, visible MATLAB session). The two hand off over the filesystem, orchestrated by the agent.
⚠️ You need your own valid CarSim (test in version 2024) and MATLAB licenses. This project does not include or circumvent any license. On a license-managed CarSim, start the CarSim License Manager (
<CarSim>\Programs\cslm.exe) before running the solver/co-sim, or CarSim returns a FlexNet error.
Features / tools (23)
Toolchain & examples
Database navigation — find & edit any GUI parameter from code
Edit tables & assemble vehicles — beyond scalars
Solve & co-simulate
The recommended co-sim path runs the driver through the MATLAB MCP, not this fallback.
Editing CarSim parameters without the GUI
CarSim's GUI is closed-source, but its data is not — every GUI dataset is a plain-text
.par file under DATA\<Library>\<Category>\. So the agent edits suspension geometry,
sprung mass, motor/engine maps, I/O channels, etc. directly, no mouse automation:
find_dataset("sprung mass") # -> the Vehicles\Sprung_Mass datasets + paths
get_dataset(path) # -> M_SU=1020 [kg], H_CG_SU=375 [mm], IZZ_SU=… (annotated)
set_dataset(path, {"M_SU": "1500"}) # -> edits + .bak + #Modified bump
Keyword dictionary (one-time, per install). get_dataset/describe_keyword annotate
keywords with meaning + units harvested from CarSim's own solver echo files
(DATA\Results\**\*_echo.par). Build it once:
build_keyword_dictionary() # -> keywords.json (local; ~2000+ keywords)
keywords.jsonis a local artifact (it contains CarSim's proprietary parameter documentation) and is.gitignored — it is generated on each user's own install, never redistributed. IfDATA\Resultsis empty, run any CarSim example once to create echo files.
Requirements
- CarSim (test in version 2024) (Windows) with a valid license. Start
cslm.exefirst if license-managed. - MATLAB (tested R2023b) + Simulink, with a valid license.
- Python 3.10+ with
mcp[cli]andscipy(seerequirements.txt). - The official MATLAB MCP server connected in your MCP client (for the co-sim run step).
The CarSim ↔ Simulink bridge (vs_sf.mexw64) and CLI solver ship with CarSim —
nothing extra to build.
Install
A. As a Claude Code plugin (recommended)
From a local clone / unzipped folder:
/plugin marketplace add /absolute/path/to/carsim-mcp
/plugin install carsim-mcp@carsim-mcp
From GitHub (after you push this repo):
/plugin marketplace add AngelZhaksy/carsim-mcp-Carsim-matlab-mcp-server
/plugin install carsim-mcp@carsim-mcp
Then install the Python deps into the python the plugin will launch:
python -m pip install -r requirements.txt
Restart Claude Code (or /reload-plugins) so the mcp__carsim__* tools load.
B. As a plain MCP server (no plugin)
Add to your MCP client config (Claude Code: ~/.claude.json → mcpServers):
{
"mcpServers": {
"carsim": {
"command": "python",
"args": ["/absolute/path/to/carsim-mcp/server.py"],
"env": {
"CARSIM_ROOT": "E:\\Carsim2024",
"MATLAB_EXE": "E:\\Program Files\\MATLAB\\R2023b\\bin\\matlab.exe"
}
}
}
}
Configuration (environment variables)
All optional — sensible defaults are auto-detected; override for your install.
Verify with the carsim_info tool: it returns ok: true when the core paths exist.
Usage — the co-simulation recipe
The agent orchestrates three steps (CarSim MCP → MATLAB MCP → CarSim MCP):
# 1) Prepare (CarSim MCP): generate a runnable co-sim package
res = carsim.scaffold_cosim(out_dir=..., simfile="...\\simfile.sim",
kind="slx", model="...\\your_model.slx", stop_time="15")
# 2) Run (MATLAB MCP): execute the driver in the warm MATLAB session
matlab.run_matlab_file(script_path=res.runner_m) # expect "COSIM_OK"
# 3) Read (CarSim MCP): parse the CarSim ERD output
carsim.read_results(path="...\\Results\\Run_<id>\\LastRun.vs") # -> channels min/max/final
kind="mfile" wraps your own MATLAB .m controller instead of an .slx.
docs/carsim-mcp-use.md— hands-on usage guide + a pitfalls table (single-space simfile,.vsbheader,Run_all.parvsRuns\, license, read-only files…). Read this before your first headless run.docs/carsim-matlab.md— co-simulation recipes & parameter editing.docs/DESIGN.md— architecture.
The CarSim solver runs as a DLL inside Simulink via the
vs_sfS-Function — you do not need the CarSim GUI open to co-simulate.
Development / tests
python -m pip install -r requirements.txt
python smoke_test.py # pure-helper checks (paths, parsfile, scaffold, examples)
python mcp_handshake_test.py # full MCP stdio handshake + carsim_info
claude plugin validate . # validate the plugin manifest
Note for contributors: never lazy-import native libs inside a tool
Claude Code runs sync MCP tools in a worker thread. Importing numpy/scipy
(or any C-extension) inside a tool function makes the first import happen in a
non-main thread, which can deadlock on the import lock (Windows) and hang the
tool forever. Keep such imports at module top level (see carsim_core.py).
Troubleshooting
- A tool hangs forever → a heavy/native import was added inside a tool function; move it to module top level (see the contributor note above).
- Code edits don't apply → MCP servers load at session start; restart Claude Code
or
/reload-plugins. - CarSim FlexNet error
-8,523/ GUI won't open → startcslm.exefirst. carsim_infoshowsexists:false→ setCARSIM_ROOT/MATLAB_EXEenv vars.
License
MIT — see LICENSE. Does not include or circumvent CarSim/MATLAB licensing; bring your own valid licenses.