让 AI Agent 直接操作 Simulink：Simulink Agentic Toolkit MCP 配置踩坑全记录

让 AI Agent 直接操作 SimulinkSimulink Agentic Toolkit MCP 配置踩坑全记录本文记录了将 Simulink Agentic Toolkit 的 MCP 服务接入 AI AgentHermes Agent实现 AI 直接调用 MATLAB/Simulink 的完整过程。包括环境配置、函数注册修复、踩坑排查以及用一个三相逆变器仿真实例验证效果。一、什么是 Simulink Agentic ToolkitSimulink Agentic Toolkit 是 MATLAB 官方提供的 MCPModel Context Protocol工具包让 AI Agent 可以通过标准化协议直接调用 MATLAB/Simulink 的功能模型读取model_overview、model_read参数查询model_query_params、model_resolve_params模型编辑model_edit、model_check代码执行evaluate_matlab_code、run_matlab_file工作原理AI Agent ←→ MCP 协议 ←→ matlab-mcp-server.exe ←→ MATLAB 引擎AI Agent 发送 JSON-RPC 请求MCP 服务器翻译成 MATLAB 命令执行返回结果。二、环境准备2.1 工具清单工具版本用途MATLABR2024b仿真引擎Simulink Agentic Toolkit0.2.0 (R2026a)MCP 工具包matlab-mcp-server.exe-MCP 服务器Hermes Agent-AI 编程助手MCP 客户端2.2 安装 Simulink Agentic Toolkit% MATLAB 命令窗口cd(E:\matlab-toolkits\simulink)satk_initialize安装后的目录结构E:\matlab-toolkits\simulink\ ├── tools\ │ ├── tools.json % MCP 工具定义函数名映射 │ └── common\ │ ├── sage\ % 命名空间函数.p 加密文件 │ │ ├── graph_read.p │ │ ├── graph_query.p │ │ └── graph_get_params.p │ └── sage\internal\ % 内部依赖 ├── satk_initialize.p % 初始化脚本 └── bin\ └── matlab-mcp-server.exe % MCP 服务器2.3 配置 AI Agent 的 MCP 连接在 Hermes Agent 的配置文件中添加 MATLAB MCP 服务器# ~/.hermes/config.yamlmcp_servers:matlab:command:E:\\matlab-toolkits\\bin\\matlab-mcp-server.exeargs:---extension-file-C:\\Users\\xxx\\.matlab\\agentic-toolkits\\simulink\\tools\\tools.json⚠️ 关键注意matlab-mcp-server.exe是 Windows 程序--extension-file参数必须用 Windows 路径格式C:\Users\...不能用 WSL 路径/mnt/c/...。这个坑花了很久才定位到。配置完成后重启 Agent看到类似以下输出说明连接成功MCP server matlab connected 14 MCP tools available: model_overview, model_read, model_query_params, ...三、踩坑函数注册完全失效3.1 现象MCP 连接成功14 个工具都列出来了但调用任何一个都报错错误: 未定义函数 model_overview3.2 排查过程第一步检查 tools.json 的函数映射{name:model_overview,function:model_overview,signature:model_overview(model, scope, detail)}MCP 服务器会调用model_overview函数但 MATLAB 中找不到这个函数。第二步查找实际函数位置which sage.graph_read E:\matlab-toolkits\simulink\tools\common\sage\graph_read.p% static method实际函数在sage命名空间下不在顶层。第三步尝试直接调用命名空间函数sage.graph_read(Inverter3Phase,root,0)错误:无法解析名称sage.internal.utils.SystemComposerUtils.getSystemComposerInfoFromPath函数内部依赖缺失第四步检查内部依赖dir(E:\matlab-toolkits\simulink\tools\common\sage\internal\)adaptercacheexprgraph SAGEContainerCategory.p SubgraphSource.pdir(E:\matlab-toolkits\simulink\tools\common\sage\internal\utils\)未找到 ← 这就是问题utils目录完全缺失导致SystemComposerUtils、StateflowUtils等类找不到。3.3 根因分析层级问题tools.json映射model_overview → model_overview但顶层函数不存在sage.graph_read存在.p 文件但内部依赖utils目录缺失satk_initialize有 autolayout 警告没有正确注册顶层函数版本兼容Toolkit 是 R2026aMATLAB 是 R2024b内部 API 不兼容核心问题R2024b 的 MATLAB R2026a 的 toolkit 版本不兼容utils目录缺失导致内部函数链断裂。3.4 解决方案分两步修复第一步创建缺失的 stub 文件utilsDirE:\matlab-toolkits\simulink\tools\common\sage\internal\utils;mkdir(utilsDir);% SystemComposerUtils - 提供空的结构体返回值fidfopen(fullfile(utilsDir,SystemComposerUtils.m),w);fprintf(fid,[...classdef SystemComposerUtils\n... methods(Static)\n... function result getSystemComposerInfoFromPath(varargin)\n... result struct();\n... result.isSystemComposer false;\n... end\n... end\n...end\n]);fclose(fid);% StateflowUtils - 返回 falsefidfopen(fullfile(utilsDir,StateflowUtils.m),w);fprintf(fid,[...classdef StateflowUtils\n... methods(Static)\n... function result isSFSID(varargin)\n... result false;\n... end\n... end\n...end\n]);fclose(fid);第二步创建原生 API 包装函数既然sage.graph_read内部还有各种问题不如直接用原生 Simulink APIget_param、find_system重写顶层函数% E:\matlab-toolkits\simulink\tools\common\model_overview.mfunctionresultmodel_overview(model,scope,detail)% ⚠️ MCP 传参可能是 string 类型必须转换ifisstring(model),modelchar(model);endifisstring(scope),scopechar(scope);endifisstring(detail),detailchar(detail);endifendsWith(model,.slx)modelmodel(1:end-4);endif~bdIsLoaded(model)load_system(model);endifnargin2||isempty(scope)||strcmp(scope,root)scopemodel;endblocksfind_system(scope,SearchDepth,1,Type,block);resultstruct();result.modelmodel;result.scopescope;result.blocks{};fori1:length(blocks)blkstruct();blk.nameblocks{i};blk.typeget_param(blocks{i},BlockType);result.blocks{end1}blk;endresult.block_countlength(result.blocks);end同样创建model_read.m、model_query_params.m、model_resolve_params.m。⚠️ 关键踩坑string 类型处理MCP 服务器传给 MATLAB 函数的参数可能是string类型而非char这会导致很多内置函数报错。每个包装函数开头都必须加ifisstring(model),modelchar(model);end验证which model_overview E:\matlab-toolkits\simulink\tools\common\model_overview.mmodel_overview(Inverter3Phase.slx,root,tree)ansmodel:Inverter3Phaseblock_count:30MCP 工具调用也恢复正常。四、验证用 AI Agent 搭建三相逆变器仿真MCP 配置好后用一个实际测试案例验证 AI Agent 能否完整操作 Simulink。4.1 测试目标让 AI Agent 自动搭建一个三相逆变器 Simulink 模型不用 Universal Bridge运行仿真并在 Scope 中显示波形。4.2 AI Agent 的操作流程通过 MCP 工具AI Agent 执行了以下操作evaluate_matlab_code检查可用的模块库% 查找 Ideal Switch 模块add_block(powerlib/Power Electronics/Ideal Switch,test/SW1);run_matlab_file运行 build_model.m 构建完整模型model_overview验证模型结构30 个模块evaluate_matlab_code运行仿真sim(Inverter3Phase);open_system(Inverter3Phase/Scope);4.3 遇到的问题问题原因解决方案From Workspace 变量丢失工作区变量被清除改用 Sine Wave MATLAB FunctionIGBT 不导通R2024b powerlib 兼容性问题改用 Ideal Switch电压测量极性反LConn1/LConn2 极性与直觉相反交换连接boolean 类型不兼容比较器输出 boolean开关需要 double加 Data Type ConversionScope 不显示LayoutDimensions 默认 [1,1]设为 [4,1]4.4 最终效果AI Agent 成功搭建了完整的三相逆变器仿真模型Scope 显示四组正确波形三相调制波正弦波120° 相移六路 PWM 脉冲信号桥臂输出电压 uabPWM 波形滤波后输出电压三相正弦波五、踩坑总结MCP 配置相关坑现象解决方案tools.json 函数映射失效model_overview 未定义创建原生 API 包装函数sage 内部依赖缺失SystemComposerUtils 找不到创建 stub .m 文件string 类型传参包装函数参数错误每个函数开头加if isstring(x), x char(x); endextension-file 路径格式MCP 服务器启动失败用 Windows 路径C:\...不用 WSL 路径Simulink 搭建相关坑现象解决方案From Workspace 变量丢失仿真报错用原生 Simulink 源模块powerlib IGBT 不导通输出恒为 0用 Ideal Switch 替代电压测量极性输出电压为负LConn1GND侧, LConn2AC侧boolean 不兼容开关不响应加 Data Type ConversionScope 布局只显示 1 个图设置 LayoutDimensions六、经验总结版本兼容性是最大的坑R2024b R2026a toolkit 的组合需要手动修复。如果 toolkit 和 MATLAB 版本匹配大部分问题不会出现。stub 包装是通用解法当 .p 加密文件的内部函数链断裂时创建 stub 文件提供最小返回值 原生 API 包装函数是最稳的方案。MCP 传参格式要注意MCP 服务器传给 MATLAB 的参数可能是string而非char每个包装函数都要处理。最简电路测试是王道遇到 Simulink 模块行为异常时不要在复杂模型里猜先用最简电路DC → 开关 → R → GND隔离问题。AI Agent MCP 的价值AI 可以快速迭代代码改一行、跑一次、看结果比手动拖拽 Simulink 模块效率高很多。但 AI 对 Simulink 底层行为的理解可能不准确需要实测验证。本文基于 MATLAB R2024b Simulink Agentic Toolkit 0.2.0不同版本的行为可能有差异。