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

让 AI Agent 直接操作 Simulink：Simulink Agentic Toolkit MCP 配置踩坑全记录需要先看清适用场景和关键步骤，避免只记结论却忽略实际限制。

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

一、什么是 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-toolkitssimulink')satk_initialize

安装后的目录结构：

E:matlab-toolkitssimulink├── 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-toolkitsbinmatlab-mcp-server.exe"args:-"--extension-file"-"C:Usersxxx.matlabagentic-toolkitssimulinktoolstools.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-toolkitssimulinktoolscommon+sagegraph_read.p% static method

实际函数在 sage 命名空间下，不在顶层。

第三步：尝试直接调用命名空间函数

>> sage.graph_read('Inverter3Phase','root',0)错误: 无法解析名称 'sage.internal.utils.SystemComposerUtils.getSystemComposerInfoFromPath'

函数内部依赖缺失！

第四步：检查内部依赖

>>dir('E:matlab-toolkitssimulinktoolscommon+sage+internal')+adapter+cache+expr+graphSAGEContainerCategory.pSubgraphSource.p>>dir('E:matlab-toolkitssimulinktoolscommon+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-toolkitssimulinktoolscommon+sage+internal+utils';mkdir(utilsDir);% SystemComposerUtils - 提供空的结构体返回值fid =fopen(fullfile(utilsDir,'SystemComposerUtils.m'),'w');fprintf(fid,[...'classdef SystemComposerUtilsn'...'methods(Static)n'...'function result = getSystemComposerInfoFromPath(varargin)n'...'result = struct();n'...'result.isSystemComposer = false;n'...'endn'...'endn'...'endn']);fclose(fid);% StateflowUtils - 返回 falsefid =fopen(fullfile(utilsDir,'StateflowUtils.m'),'w');fprintf(fid,[...'classdef StateflowUtilsn'...'methods(Static)n'...'function result = isSFSID(varargin)n'...'result = false;n'...'endn'...'endn'...'endn']);fclose(fid);

第二步：创建原生 API 包装函数

既然 sage.graph_read 内部还有各种问题，不如直接用原生 Simulink API（get_param、find_system）重写顶层函数：

% E:matlab-toolkitssimulinktoolscommonmodel_overview.mfunction result =model_overview(model, scope, detail)% ⚠️ MCP 传参可能是 string 类型，必须转换ifisstring(model), model =char(model);endifisstring(scope), scope =char(scope);endifisstring(detail), detail =char(detail);endifendsWith(model,'.slx')model =model(1:end-4);endif~bdIsLoaded(model)load_system(model);endif nargin <2||isempty(scope)||strcmp(scope,'root')scope = model;endblocks =find_system(scope,'SearchDepth',1,'Type','block');result =struct();result.model = model;result.scope = scope;result.blocks ={};fori=1:length(blocks)blk =struct();blk.name = blocks{i};blk.type =get_param(blocks{i},'BlockType');result.blocks{end+1}= blk;endresult.block_count =length(result.blocks);end

同样创建 model_read.m、model_query_params.m、model_resolve_params.m。

关键踩坑：string 类型处理

MCP 服务器传给 MATLAB 函数的参数可能是 string 类型（而非 char），这会导致很多内置函数报错。每个包装函数开头都必须加：

ifisstring(model), model =char(model);end

验证：

>> which model_overviewE:matlab-toolkitssimulinktoolscommonmodel_overview.m>>model_overview('Inverter3Phase.slx','root','tree')ans = model:'Inverter3Phase'block_count:30

MCP 工具调用也恢复正常。

四、验证：用 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，不同版本的行为可能有差异。