Carsim Mcp Carsim Matlab

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

Tool	What it does
carsim_info	Resolve & existence-check every path (root, GUI, CLI solver, vs_sf mex, MATLAB, DB). The "is it wired up" probe.
launch_gui	Open the CarSim GUI (optional; not needed for editing params or co-sim).
list_examples	List shipped CPAR archives + Simulink example models.

Database navigation — find & edit any GUI parameter from code

Tool	What it does
list_libraries	List the GUI libraries (DATA subfolders: Suspensions, Powertrain, Vehicles, Steering, Tires, IO_Channels…) with dataset counts + categories.
browse_library	List datasets in a library/category, each with its GUI identity + file path.
find_dataset	Fuzzy-search the whole database by GUI text — "where do I set X" (find_dataset('motor'), find_dataset('sprung mass')).
get_dataset	Structured read: identity + scalar params + tables, each annotated with meaning + unit from the keyword dictionary.
set_dataset	Edit scalar params ({M_SU: 1500, H_CG_SU: 530}), bump #Modified, auto .bak. Handles read-only library files.
describe_keyword	Look up a keyword's meaning + unit (describe_keyword('M_SU') → sprung mass, kg).
build_keyword_dictionary	Build the local keyword dictionary from CarSim's own echo files (run once per install).
read_parsfile / write_parsfile	Low-level keyword read/edit (auto .bak; write_parsfile takes occurrence=N for repeated keywords).

Edit tables & assemble vehicles — beyond scalars

Tool	What it does
set_table	Rewrite a TABLE block (motor torque map, tire Pacejka carpet, battery OCV-vs-SOC, spring/damper curve). Verifies after write.
get_links	List a dataset's subsystem links (PARSFILE lines) with slot labels + identity — what an assembly contains.
set_link	Swap one subsystem link (e.g. drop an EV powertrain into a vehicle); updates the #BlueLink too.
resolve_assembly	Recurse the full vehicle tree (Vehicle → Powertrain → HEV(battery/motors) → tables).
clone_dataset	Copy a dataset to a new .par with a fresh #FileID + identity.
consolidate_run	Experimental/inspection: flatten the link tree into one file (not parse-order-runnable for complex vehicles — edit a baked Run_all.par to run).

Solve & co-simulate

Tool	What it does
run_solver	Headless CarSim solve via the CLI solver wrapper (no MATLAB, no GUI).
generate_simfile	Produce a co-sim simfile by templating from a GUI-generated one.
scaffold_cosim	Generate a ready-to-run co-sim package (.slx or .m driver + run_cosim.m).
read_results	Parse CarSim ERD (.vs JSON + .vsb float32) or a .mat into per-channel {len,min,max,final,unit}. pattern= filters channels (a full run can have 1000+); names_only= lists names fast.
run_cosim_headless	Optional fallback: run a driver via matlab -batch (unattended).

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.json is a local artifact (it contains CarSim's proprietary parameter documentation) and is .gitignored — it is generated on each user's own install, never redistributed. If DATA\Results is empty, run any CarSim example once to create echo files.

---

Requirements

• CarSim (test in version 2024) (Windows) with a valid license. Start cslm.exe first if license-managed.
• MATLAB (tested R2023b) + Simulink, with a valid license.
• Python 3.10+ with mcp[cli] and scipy (see requirements.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.

Var	Default	Meaning
CARSIM_ROOT	E:\Carsim2024	CarSim install root
CARSIM_DB	auto (<root>\DATA)	CarSim working database
MATLAB_EXE	auto-detected R20xx	MATLAB executable

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, .vsb header, Run_all.par vs Runs\, 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_sf S-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 → start cslm.exe first.
• carsim_info shows exists:false → set CARSIM_ROOT / MATLAB_EXE env vars.

---

License

MIT — see LICENSE. Does not include or circumvent CarSim/MATLAB licensing; bring your own valid licenses.