让 AI Agent 直接操作 Simulink：Simulink Agentic Toolkit MCP 配置踩坑全记录
本文作者ChanChou授权发布于本站 | CSDN原文
本文记录了将 Simulink Agentic Toolkit 的 MCP 服务接入 AI Agent（Hermes Agent），实现 AI 直接调用 MATLAB/Simulink 的完整过程。包括环境配置、函数注册修复、踩坑排查，以及用一个三相逆变器仿真实例验证效果。
一、什么是 Simulink Agentic Toolkit
Simulink Agentic Toolkit 是 MATLAB 官方提供的 MCP（Model 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 工具清单
| 工具 | 版本 | 用途 |
|---|---|---|
| MATLAB | R2024b | 仿真引擎 |
| Simulink Agentic Toolkit | 0.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 服务器：
mcp_servers: matlab: command: "E:\\matlab-toolkits\\bin\\matlab-mcp-server.exe" args: - "--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' connected14 MCP tools available: model_overview, model_read, model_query_params, ...三、踩坑：函数注册完全失效
3.1 现象
MCP 连接成功，14 个工具都列出来了，但调用任何一个都报错：
错误: 未定义函数 'model_overview'3.2 排查过程
第一步：检查 tools.json 的函数映射
{ "name": "model_overview", "function": "model_overview", "signature": "model_overview(model, scope, detail)"}MCP 服务器会调用 model_overview 函数，但 MATLAB 中找不到这个函数。
第二步：查找实际函数位置
>> which sage.graph_readE:\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\')+adapter +cache +expr +graph SAGEContainerCategory.p SubgraphSource.p
>> dir('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 是 R2026a，MATLAB 是 R2024b，内部 API 不兼容 |
核心问题：R2024b 的 MATLAB + R2026a 的 toolkit 版本不兼容，+utils 目录缺失导致内部函数链断裂。
3.4 解决方案
分两步修复：
第一步：创建缺失的 stub 文件
utilsDir = 'E:\matlab-toolkits\simulink\tools\common\+sage\+internal\+utils';mkdir(utilsDir);
% SystemComposerUtils - 提供空的结构体返回值fid = fopen(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 - 返回 falsefid = fopen(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 API（get_param、find_system）重写顶层函数：
% E:\matlab-toolkits\simulink\tools\common\model_overview.mfunction result = model_overview(model, scope, detail) % ⚠️ MCP 传参可能是 string 类型，必须转换 if isstring(model), model = char(model); end if isstring(scope), scope = char(scope); end if isstring(detail), detail = char(detail); end
if endsWith(model, '.slx') model = model(1:end-4); end
if ~bdIsLoaded(model) load_system(model); end
if nargin < 2 || isempty(scope) || strcmp(scope, 'root') scope = model; end
blocks = find_system(scope, 'SearchDepth', 1, 'Type', 'block'); result = struct(); result.model = model; result.scope = scope; result.blocks = {}; for i = 1:length(blocks) blk = struct(); blk.name = blocks{i}; blk.type = get_param(blocks{i}, 'BlockType'); result.blocks{end+1} = blk; end result.block_count = length(result.blocks);end同样创建 model_read.m、model_query_params.m、model_resolve_params.m。
⚠️ 关键踩坑：string 类型处理
MCP 服务器传给 MATLAB 函数的参数可能是 string 类型（而非 char），这会导致很多内置函数报错。每个包装函数开头都必须加：
if isstring(model), model = char(model); end验证：
>> which model_overviewE:\matlab-toolkits\simulink\tools\common\model_overview.m
>> model_overview('Inverter3Phase.slx', 'root', 'tree')ans = model: 'Inverter3Phase' block_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 Function |
| IGBT 不导通 | R2024b powerlib 兼容性问题 | 改用 Ideal Switch |
| 电压测量极性反 | LConn1/LConn2 极性与直觉相反 | 交换连接 |
| boolean 类型不兼容 | 比较器输出 boolean，开关需要 double | 加 Data Type Conversion |
| Scope 不显示 | LayoutDimensions 默认 [1,1] | 设为 [4,1] |
4.4 最终效果
AI Agent 成功搭建了完整的三相逆变器仿真模型，Scope 显示四组正确波形：
- 三相调制波（正弦波，120° 相移）
- 六路 PWM 脉冲信号
- 桥臂输出电压 uab（PWM 波形）
- 滤波后输出电压（三相正弦波）
五、踩坑总结
MCP 配置相关
| 坑 | 现象 | 解决方案 |
|---|---|---|
| tools.json 函数映射失效 | model_overview 未定义 | 创建原生 API 包装函数 |
| sage 内部依赖缺失 | SystemComposerUtils 找不到 | 创建 stub .m 文件 |
| string 类型传参 | 包装函数参数错误 | 每个函数开头加 if isstring(x), x = char(x); end |
| extension-file 路径格式 | MCP 服务器启动失败 | 用 Windows 路径（C:\...），不用 WSL 路径 |
Simulink 搭建相关
| 坑 | 现象 | 解决方案 |
|---|---|---|
| From Workspace 变量丢失 | 仿真报错 | 用原生 Simulink 源模块 |
| powerlib IGBT 不导通 | 输出恒为 0 | 用 Ideal Switch 替代 |
| 电压测量极性 | 输出电压为负 | LConn1=GND侧, LConn2=AC侧 |
| boolean 不兼容 | 开关不响应 | 加 Data Type Conversion |
| Scope 布局 | 只显示 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，不同版本的行为可能有差异。
如果这篇文章对你有帮助，欢迎分享给更多人！
部分信息可能已经过时