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

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

本文记录了将 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 工具清单

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.yaml
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' connected
14 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_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\\')
+adapter +cache +expr +graph SAGEContainerCategory.p SubgraphSource.p

>> dir('E:\\matlab-toolkits\\simulink\\tools\\common\\+sage\\+internal\\+utils\\')
未找到 ← 这就是问题！

+utils 目录完全缺失，导致 SystemComposerUtils、StateflowUtils 等类找不到。

3.3 根因分析

核心问题：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 – 返回 false
fid = 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.m
function 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_overview
E:\\matlab–toolkits\\simulink\\tools\\common\\model_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 执行了以下操作：

% 查找 Ideal Switch 模块
add_block('powerlib/Power Electronics/Ideal Switch', 'test/SW1');

sim('Inverter3Phase');
open_system('Inverter3Phase/Scope');

4.3 遇到的问题

4.4 最终效果

AI Agent 成功搭建了完整的三相逆变器仿真模型，Scope 显示四组正确波形：

五、踩坑总结

MCP 配置相关

Simulink 搭建相关

六、经验总结

本文基于 MATLAB R2024b + Simulink Agentic Toolkit 0.2.0，不同版本的行为可能有差异。