convez.ai
MCP ServerIntegração & APIsAvançado
AngelZhaksy

CarSim MCP — Servidor de Co-simulação CarSim-MATLAB

AngelZhaksy/carsim-mcp-Carsim-matlab-mcp-server

Automatize simulações CarSim + MATLAB do Claude com acesso total ao banco de dados

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra CarSim (simulador automotivo) com Claude e MATLAB/Simulink, permitindo editar parâmetros, executar simulações headless e orquestrar co-simulações. Oferece 17 ferramentas para navegação de banco de dados, edição de parâmetros sem GUI e execução de solver com delegação de MATLAB para o servidor oficial.

Instalação

$npx convez-ai AngelZhaksy/carsim-mcp-Carsim-matlab-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
14
Forks
3
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Simulação automotiva headless sem GUI CarSim
  • Co-simulação CarSim-MATLAB com controladores .m e modelos .slx
  • Edição programática de parâmetros de suspensão, motor e dinâmica veicular
  • Orquestração de workflows de engenharia automotiva via Claude

Veredito

MCP robusto e bem documentado para simulação automotiva, mas exige licenças válidas de CarSim e MATLAB. Ideal para engenheiros de veículos que já usam essas ferramentas e buscam automação via IA; não é útil sem o ecossistema CarSim-MATLAB instalado.

README

A tradução para o português deste README ainda está na fila.

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 (17)

Toolchain & examples

ToolWhat it does
carsim_infoResolve & existence-check every path (root, GUI, CLI solver, vs_sf mex, MATLAB, DB). The "is it wired up" probe.
launch_guiOpen the CarSim GUI (optional; not needed for editing params or co-sim).
list_examplesList shipped CPAR archives + Simulink example models.

Database navigation — find & edit any GUI parameter from code

ToolWhat it does
list_librariesList the GUI libraries (DATA subfolders: Suspensions, Powertrain, Vehicles, Steering, Tires, IO_Channels…) with dataset counts + categories.
browse_libraryList datasets in a library/category, each with its GUI identity + file path.
find_datasetFuzzy-search the whole database by GUI text — "where do I set X" (find_dataset('motor'), find_dataset('sprung mass')).
get_datasetStructured read: identity + scalar params + tables, each annotated with meaning + unit from the keyword dictionary.
set_datasetEdit scalar params ({M_SU: 1500, H_CG_SU: 530}), bump #Modified, auto .bak. Handles read-only library files.
describe_keywordLook up a keyword's meaning + unit (describe_keyword('M_SU') → sprung mass, kg).
build_keyword_dictionaryBuild the local keyword dictionary from CarSim's own echo files (run once per install).
read_parsfile / write_parsfileLow-level keyword read/edit (auto .bak). get_dataset/set_dataset are the friendlier layer.

Solve & co-simulate

ToolWhat it does
run_solverHeadless CarSim solve via the CLI solver wrapper (no MATLAB, no GUI).
generate_simfileProduce a co-sim simfile by templating from a GUI-generated one.
scaffold_cosimGenerate a ready-to-run co-sim package (.slx or .m driver + run_cosim.m).
read_resultsParse CarSim ERD (.vs JSON + .vsb float32) or a .mat into per-channel {len,min,max,final}.
run_cosim_headlessOptional 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.

VarDefaultMeaning
CARSIM_ROOTE:\Carsim2024CarSim install root
CARSIM_DBauto (<root>\DATA)CarSim working database
MATLAB_EXEauto-detected R20xxMATLAB 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.

Ver o original no GitHub

Bom para

Relacionados