🔗 SimuBridge

AI 驱动的 Simulink 技能包 + MCP 后端

English README

---

这是什么

simubridge-skills 是一个 Claude Code / Codex 技能项目，让 AI 助手能直接用自然语言操控 MATLAB Simulink。它包含：

• 🎯 技能包（skill/simubridge/）— 教 AI 如何高效使用 Simulink 工具的提示词集合
• 🔧 MCP 服务端（src/simubridge/）— 连接 MATLAB 引擎的本地后端，提供 20+ 个工具

技能是主体，MCP 是后端。 用户安装技能后，AI 就知道如何一步步构建、修改、仿真 Simulink 模型。

---

技能索引

技能	状态	用途	触发词
simubridge	Stable	Simulink 模型创建、查看、修改、仿真	"Simulink"、"打开模型"、"加个模块"、"连线"、"仿真"、"子系统"

---

快速开始

环境要求

• MATLAB R2021a+（需包含 Simulink）
• Python 3.9–3.12（⚠️ 3.13 不支持 MATLAB 引擎）

---

第 1 步：准备正确的 Python 版本

MATLAB 引擎只支持 Python 3.9–3.12。如果你的默认 Python 是 3.13+，需要单独安装一个 3.11/3.12。

本教程以 Python 3.12 为例，安装到 C:\Python312。你也可以用 3.11（C:\Python311）。

# 确认你的 Python 版本
python --version

如果显示 3.13.x，从 https://www.python.org 下载安装 Python 3.12，取消勾选 "Add to PATH"，安装到自定义路径（如 C:\Python312）。

---

第 2 步：安装 MATLAB Python 引擎

在 MATLAB 中运行 matlabroot 获取安装路径，然后用你准备好的 Python 安装引擎：

# 先装 setuptools
C:\Python312\python.exe -m pip install setuptools

# 进入 MATLAB 引擎目录（路径换成你的）
cd "你的MATLAB路径\extern\engines\python"
C:\Python312\python.exe setup.py install

验证：

C:\Python312\python.exe -c "import matlab.engine; print('OK')"

常见问题

错误	原因	解决
Install setuptools	缺少 setuptools	python -m pip install setuptools
permission denied	无管理员权限	python setup.py install --user
supports Python 3.9–3.12, but your version is 3.13	Python 版本太高	用第 1 步装的 3.12 运行
'matlab' is not a package	当前目录冲突	换个目录运行验证命令

---

第 3 步：安装 MCP 后端

git clone https://github.com/naaomiur/simubridge-skills.git
cd simubridge-skills

# 用你准备好的 Python 安装
C:\Python312\python.exe -m pip install -e .

验证：

C:\Python312\python.exe -m simubridge

⚠️ 终端会卡住不退出——这是正常的，MCP 在等待 stdio 连接。按 Ctrl+C 停掉。

---

第 4 步：配置 Claude Code MCP

编辑 C:\Users\你的用户名\.claude.json，在 "mcpServers" 中添加：

"simubridge": {
  "command": "P:\\code\\Python3.12\\python.exe",
  "args": ["-m", "simubridge"]
}

⚠️ JSON 不支持注释，不要把说明文字写进去。路径里反斜杠要双写 \\。

完整示例：

{
  "mcpServers": {
    "simubridge": {
      "command": "P:\\code\\Python3.12\\python.exe",
      "args": ["-m", "simubridge"]
    }
  }
}

保存后重启 Claude Code。

---

第 5 步：验证 MCP 连接

在 Claude Code 中输入：

/mcp

看到 simubridge 显示绿色 Connected 即成功。26 个工具自动加载。

---

第 6 步：配置 MATLAB 共享引擎

在 MATLAB 命令窗口中运行：

matlab.engine.shareEngine('SIMULINK_MCP_SESSION')

💡 写入 startup.m 每次启动自动共享：

edit(fullfile(userpath, 'startup.m'))

---

第 7 步：安装技能

mkdir -p ~/.claude/skills
cp -R skill/simubridge ~/.claude/skills/

技能教 Claude 如何高效使用 Simulink 工具。即使不装也能用（MCP 自带工具描述），装了效果更好。

---

开始使用

在 Claude Code 中试试：

打开 mymodel.slx，在 Voltage Source 后面加一个 Gain 模块，增益 2.5，连到 Scope

---

技能能力

分类	工具	功能
模型	open_model / create_model / close_model / save_model	模型生命周期
模块	add_block / delete_block / search_library / describe_block	模块管理
参数	get_block_params / set_block_params / get_model_config / set_model_config	参数配置
连线	connect / delete_line	信号/功率连线（支持批量）
检查	model_audit / get_block_ports	拓扑审计
Stateflow	get_mfunction_code / set_mfunction_code	MATLAB Function 代码读写
仿真	simulate_and_analyze_waveform	仿真 + 波形分析
工作区	get_workspace_vars / set_workspace_vars	MATLAB 工作区读写
子系统	create_subsystem / expand_subsystem / 端口管理	子系统操作
万能	eval_matlab	执行任意 MATLAB 代码

📖 完整中英双语工具说明：skill/simubridge/SKILL.md

---

架构

┌─────────────────┐     技能       ┌──────────────┐    MCP stdio     ┌──────────────┐  MATLAB API  ┌──────────┐
│  Claude / Codex  │ ◄───────────  │  simubridge   │ ◄──────────────► │  MCP Server   │ ◄───────────► │  MATLAB  │
│  + 技能提示词     │               │  (技能定义)    │                  │  (Python 后端) │               │(Simulink)│
└─────────────────┘               └──────────────┘                  └──────────────┘               └──────────┘

• 技能层：skill/simubridge/SKILL.md — 教 AI 每个工具的用途和参数
• 传输层：MCP stdio — 本地进程通信，无网络依赖
• 引擎层：matlab.engine API — 连接你正在使用的 MATLAB 会话
• 自动保存：每次写入操作后自动保存，GUI 中立即可见

---

项目结构

simubridge-skills/
├── skill/simubridge/               # 🎯 技能包（主体）
│   ├── README.md                    #    技能说明
│   ├── SKILL.md                     #    技能定义（中英双语工具详解）
│   └── references/
│       └── tool-guide.md            #    工具速查表
├── src/simubridge/                  # 🔧 MCP 后端
│   ├── __init__.py                  #    入口 + 工具注册
│   ├── app.py                       #    FastMCP + MATLAB 引擎管理
│   └── tools/                       #    7 个工具模块
├── examples/
│   └── basic_usage.md               #    使用示例
├── pyproject.toml
├── claude_desktop_config.json
├── LICENSE
├── README.md                        #    中文版（本文件）
└── README_EN.md                     #    英文版

---

开源协议

MIT License — 详见 LICENSE。

⚠️ MATLAB 和 Simulink 是 The MathWorks, Inc. 的注册商标。本项目与 MathWorks 无关，亦未获其背书。

---

致谢

基于 FastMCP 和 Model Context Protocol 构建。