CarMaker

carmaker-mcp

一个 MCP 服务，让 AI Agent 能在你的计算机上操控 IPG CarMaker：启动会话、运行测试、读取结果、更改车辆数据和 Simulink 控制器参数，并撤销所做的更改。

非官方社区项目，与 IPG Automotive 或 MathWorks 无关联，也未获得其认可。你需要自备 CarMaker 和 MATLAB/Simulink 许可证。本仓库不包含任何 IPG 或 MathWorks 代码或数据。

状态：alpha。 在一套环境（CarMaker 14.1.1、MATLAB R2024b、Windows 11）上开发和测试。 docs/verification.md 列出了已在真实软件上验证和未经验证的内容。

目录： 功能 · 不涵盖的内容 · 要求 · 设置 · 与 MATLAB MCP 服务配合使用 · 设置项 · 工具 · 安全与隐私 · 故障排除 · 工作原理

功能

连接服务后，你可以向 Agent 提出以下要求：

• “运行制动测试，并告诉我停车距离。”
• “将控制器模型中的 Kp_yaw 设为 1.5，再次运行蛇形测试，并比较横摆角速度。”
• “使用 280、300 和 320 kg 的车辆质量尝试变道，并以表格列出横向加速度。”
• “上一次运行中止了。为什么？”
• “撤销你所做的一切更改。”

它有两种工作方式，Agent 会选择适合车辆的一种：

更多示例： docs/examples.md。

不支持的功能

该服务是为 Formula Student 车队的车辆动力学和控制器工作编写的，其中每次运行要么是独立运行，要么是 CarMaker for Simulink 运行。CarMaker 能做的远不止这些，其他功能不在本服务的范围内，也未经测试。

不支持（没有对应的工具）：

• 其他平台和产品： Linux；TruckMaker 和 MotorcycleMaker；CarMaker HIL 和 CarMaker Office Extended（实时硬件、Fail Safe Tester、CAN、FlexRay、SOME/IP、XCP 等总线接口）。
• CarMaker 自带的测试自动化功能： Test Manager 和测试系列、测试报告、并行（HPC）执行、使用启动文件的批处理模式。本服务会自行运行参数研究，每次运行一个。
• 构建场景： Scenario Editor，以及道路、交通、传感器、环境和 OpenSCENARIO 导入。cm_edit 会更改现有文件中的键值，但不会创建这些内容。
• 大多数可视化功能： Movie NX、IPGControl、Instruments、视频导出、Model Check。对于 IPGMovie，仅支持单张图片。
• 其他结果格式： 仅读取 .erg 文件，不读取 MDF 或 ASCII。
• 重新构建仿真程序： 使用 C 代码或通过 Simulink Coder 生成的模型。
• 远程计算机： CarMaker 和 MATLAB 必须运行在本服务所在的计算机上。

可能可用，但从未测试：

• FMU、导出为 FMU 的 CarMaker、第三方轮胎模型和其他协同仿真工具。
• 加密或受保护的数据文件。
• 上文未提及的 CarMaker 和 MATLAB 版本；同时运行多个 MATLAB 会话或 CarMaker GUI。
• 并行运行多个独立运行、暂停并恢复独立运行、对独立运行进行参数研究。
• 包含交通、传感器或驾驶辅助功能的测试运行。这些功能并无障碍，但迄今为止的所有检查都使用了不包含这些功能的车辆动力学运行。

各工具的状态见 docs/verification.md。欢迎提供其他设置的测试报告。

要求

• Windows 10 或 11
• IPG CarMaker 及其 Python API（基于 14.1.1 开发）
• 对于连接 MATLAB 的会话：CarMaker for Simulink 和 MATLAB R2022b 或更高版本，具体取决于 CarMaker 支持的版本（请参阅步骤 1中的表格；仅测试过 R2024b）
• uv（用于获取服务及其 Python 环境；也可使用 pip，参见 docs/setup.md）
• 一个 MCP 客户端：Claude Code、Claude Desktop、带 GitHub Copilot 的 VS Code、Codex、Antigravity、Cursor，……

设置

1. 检查你的计算机

uvx carmaker-mcp doctor

此命令会查找 CarMaker 和 MATLAB 的安装，告知你有哪些配置不兼容以及如何修复，并输出适用于你的计算机的 uvx 参数。参数如下所示：

uvx --python 3.12 --with matlabengine==24.2.* carmaker-mcp

这两个额外参数很重要，因此工具会为你计算出合适的参数：

• --python 3.12 用于选择 CarMaker 和你的 MATLAB 版本都兼容的 Python 版本。如果不指定，uvx 可能会选择较新的 Python，导致两者都无法使用。
• --with "matlabengine==24.2.*" 用于添加适用于你的 MATLAB 版本的 MATLAB 引擎包。如果你只使用独立运行模式，可以不添加此参数。

这两个参数都取决于 MATLAB 版本，因为 MathWorks 每个版本都会发布一个引擎包，而且每个包只能安装在部分 Python 版本上：

只有 R2024b 这一行经过真实软件测试。其他版本的信息依据已发布的引擎包要求推导，未经测试；欢迎反馈。MATLAB R2022a 及更早版本无法用于连接 MATLAB 的会话，因为其引擎包需要的 Python 版本低于此服务支持的版本（独立运行模式仍可正常使用）。

无需安装 CarMaker 即可查看这些工具：uvx carmaker-mcp --mock。

2. 在 MCP 客户端中注册服务

每个客户端都需要相同的三项内容：命令 uvx、步骤 1 中的参数，以及通过环境变量设置的配置。通常需要设置以下配置：

• CM_PROJECT：CarMaker 项目文件夹。
• CM_MATLAB_INIT：如果你通常通过运行项目的 MATLAB 脚本开始工作（例如添加文件夹到路径并打开模型的脚本），请在此处填写脚本名称，以便 Agent 也运行它。
• CM_MODEL：Agent 开始会话时打开的 Simulink 模型。可以是 MATLAB 路径上的名称，也可以是相对于项目 src_cm4sl 文件夹的路径。如果不填写，Agent 会显示找到的模型，并让你选择一个或自行选择。

选择下方的客户端。示例假设使用 MATLAB R2024b 和 Python 3.12；请将参数替换为 doctor 输出的内容。或者让服务为你写入配置项，并自动填入 shell 中设置的所有 CM_ 变量：

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

在 JSON 和 TOML 中，Windows 路径需要使用双反斜杠或正斜杠。目前只有 Claude Code 实际用于此服务；其他配置项遵循各客户端文档中说明的格式。

3. 开始会话

例如，向 Agent 发送“启动 CarMaker 并运行制动测试运行”。如果 MATLAB、模型和 CarMaker GUI 尚未打开，Agent 会将它们打开，但绝不会关闭任何内容。

如果你更希望自行打开 MATLAB 和 CarMaker，请在每个 MATLAB 会话中运行一次此命令（或将其放入 startup.m），以便服务能够连接：

matlab.engine.shareEngine('cm_mcp')

独立运行时不需要这些设置。

与 MATLAB MCP 服务配合使用

对于 CarMaker for Simulink 工作，建议也连接 MathWorks 的 MATLAB MCP Core Server。它是可选的， 独立运行时不需要它。两个服务各司其职：

同时使用两者时，请注意：

• 让两者使用同一个 MATLAB 会话（按照其 README 中的说明，将 MATLAB 服务设置为使用已打开的 MATLAB）， 这样它们看到的模型和工作区才相同。开发期间就是这样配合使用的。
• MATLAB 一次只能处理一项任务。模型编译或仿真运行期间，通过 MATLAB 服务发起的调用会等待。此服务的运行工具 正是围绕这一点设计的（采用有时限的等待，并重复等待）。
• 使用此服务的工具启动和停止运行，以便它跟踪运行情况（结果文件、错误、存储模式）。
• 通过 MATLAB 服务运行脚本可能会将 MATLAB 的工作文件夹移出 CarMaker 项目。这样一来，CarMaker for Simulink 会在下一次启动时停止，并询问项目目录。此服务会在加载或启动测试运行前将文件夹切回原位，并在结果中说明这一点。
• 通过 MATLAB 服务进行的更改不会记录在此服务的更改日志中，cm_revert_all 也不会撤销这些更改。
• 如果安装了多个 MATLAB 发行版，请确保 MATLAB 服务使用 CarMaker 所用的发行版（carmaker-mcp doctor 会显示其名称）。 使用更新发行版启动的 MATLAB 服务无法看到你的模型或 CarMaker 会话。

在同一个 CarMaker 上进行多个对话。 每个客户端和对话都会启动各自的服务，而它们操作的是同一个 MATLAB 和 CarMaker。某个对话运行参数研究期间，其他对话会拒绝加载、启动或停止任何内容，并说明当前正在运行的任务；cm_status 会将其显示为 study_running。参数研究之外则没有此类保护：两个对话同时启动单次运行时，会互相干扰。

设置

所有设置均为客户端入口中的环境变量，按上文的 CM_PROJECT 和 CM_MODEL 方式设置。

常用设置

高级设置

工具

每个工具都会告知客户端它是只读、会更改状态还是具有破坏性，以便客户端在必要时请求确认。每个参数的说明见 docs/tools.md。

会话与运行

结果

项目数据与参数

独立运行（不使用 MATLAB）

历史记录

该服务还提供资源（carmaker://guide、carmaker://status、carmaker://changelog、 carmaker://log）和三个提示词（run_and_summarise、compare_settings、undo_session）。

安全与隐私

此服务可以启动仿真，并直接编辑项目文件和正在运行的 Simulink 模型。请只将它连接到你信任的 Agent。

如何保护你的工作：

• 每个文件在首次更改前都会备份，每次更改都会记录旧值，而 cm_revert_all 可以撤销会话中的更改。
• 仅当仿真处于空闲状态时，才会在项目文件夹内写入文件。不会有工具删除项目文件。
• 原始 Tcl 和 Simulink 结构编辑默认关闭，除非你通过 CM_ENABLE 启用。
• 默认情况下，CarMaker 弹窗会等待你点击。如果设置了 CM_POPUP_TIMEOUT，遇到诸如“Vehicle not saved. All changes will be lost. OK to continue?” 的问题时，系统会采用默认选项作答，也就是在 CarMaker GUI 中丢弃未保存的更改。

运行时会在项目的 SimOutput 文件夹中写入结果文件和日志文件；撤销操作不会删除这些文件。

此服务不会收集遥测数据，也不会主动建立网络连接。它只与本机上的 MATLAB 和 CarMaker 通信。详情见： docs/safety.md。

故障排除

请先运行 uvx carmaker-mcp doctor：它会列出大多数设置问题及其解决方法。

更多信息：docs/troubleshooting.md。 服务自身的日志位于状态文件夹中的 server.log。

工作原理

• 连接 MATLAB 的会话： 服务通过 MATLAB Engine for Python 连接到 MATLAB，并通过 CarMaker for Simulink 自带的 cmguicmd（GUI 的 Tcl / ScriptControl 接口）向 CarMaker GUI 发送命令。
• 独立运行： 服务使用从 CarMaker 安装目录加载的 IPG Python API cmapi，启动并控制单独的 CarMaker 进程。
• 项目文件由保留字节的 CarMaker infofile 格式编辑器修改，结果则由用于 .erg 文件的 NumPy 读取器读取（并与 MATLAB 的 cmread 进行过核对）。

本项目不捆绑或再分发 IPG 或 MathWorks 的任何内容。

文档与贡献

• 详细设置说明（pip、更新、单文件可执行程序）
• 示例会话
• 工具参考
• 已验证内容
• 贡献指南：尤其欢迎提交其他 CarMaker 和 MATLAB 版本的测试报告
• 安全策略

相关项目：pycarmaker 与独立 CarMaker 程序的命令端口通信。本项目还支持 CarMaker for Simulink，使用 IPG 自有接口，且与其没有共享代码。

许可证

MIT，详见 LICENSE。