Codex + MATLAB MCP + R2022a 使用总结

概述

本文档记录了在 MATLAB R2022a 上配置和使用 Codex 与 MATLAB MCP Server 的完整过程，包括遇到的问题、解决方案和兼容性说明。

环境信息

项目	版本
MATLAB	R2022a (9.12.0.1884302)
Simulink	10.5
MATLAB MCP Server	v0.11.2
Simulink Agentic Toolkit	最新 (来自 GitHub)
Codex	26.715.61943
操作系统	Windows 11 企业版 LTSC

安装步骤

1. 下载 MATLAB MCP Server

从 GitHub Releases 下载 matlab-mcp-server-windows-x64.exe，放到指定目录，例如：

C:\Users\<用户名>\matlab-mcp-server\matlab-mcp-server-windows-x64.exe

2. 安装 MATLAB Toolbox

system('matlab-mcp-server-windows-x64.exe --setup-matlab')

这一步会在 MATLAB 中安装 mcpserver 工具箱，提供 shareMATLABSession() 等功能。

3. 下载 Simulink Agentic Toolkit

git clone https://github.com/matlab/simulink-agentic-toolkit.git

将 tools 目录下的 MATLAB 函数添加到 MATLAB 路径：

addpath(genpath('C:\Users\<用户名>\matlab-mcp-server\simulink-tools\tools'));
savepath;

4. 配置 Codex

编辑 ~/.codex/config.toml，添加 MCP 服务器配置：

[mcp_servers.matlab]
type = "stdio"
command = 'C:\Users\<用户名>\matlab-mcp-server\matlab-mcp-server-windows-x64.exe'
args = ['--matlab-session-mode', 'new', '--matlab-root', 'd:\Program Files\MATLAB\R2022a', '--extension-file', 'C:\Users\<用户名>\matlab-mcp-server\simulink-tools\tools\tools.json']
tool_timeout_sec = 600

[mcp_servers.matlab.env]
WINDIR = 'C:\Windows'

注意：--matlab-session-mode 必须使用 new（不是 spawn，新版已改名）。

5. 重启 Codex Desktop

修改 config.toml 后，必须完全关闭并重启 Codex Desktop 才能生效。

兼容性说明

R2022a 支持情况

功能	R2022a 支持？	说明
MATLAB MCP 服务器启动	✅	使用 new 模式自动启动 MATLAB 进程
shareMATLABSession()	❌	需要 R2023a+，依赖 dotnetenv()
evaluate_matlab_code 执行 MATLAB 代码	✅	直接调用 MATLAB 标准 API
Simulink 标准 API（add_block, add_line 等）	✅	完全兼容
Simulink Agentic Toolkit 8 个工具函数	❌	内部依赖 dictionary 函数，需要 R2022b+

8 个不可用的工具

以下工具因为依赖 dictionary()（R2022b 引入）而无法在 R2022a 上使用：

1. model_overview — 获取模型概览
2. model_read — 读取模型结构
3. model_edit — 编辑模型（增删改连线）
4. model_check — 模型结构检查
5. model_query_params — 查询模块参数
6. model_resolve_params — 解析变量引用
7. model_read_diagnostics — 读取诊断信息
8. model_test — 执行模型测试

替代方案

虽然专用工具不可用，但可以通过 evaluate_matlab_code 调用 MATLAB 标准 API 完成所有操作：

操作	标准 API
创建模型	new_system(), open_system()
添加模块	add_block()
连线	add_line()
设置参数	set_param()
读取参数	get_param()
查找模块	find_system()
保存模型	save_system()
仿真	sim()

常见问题

Q: shareMATLABSession() 报错

错误使用 mcpserver.internal.connector.internal.apikeymanager.DefaultAPIKeyManager/getAPIKey
Connecting to an existing session with shareMATLABSession() requires MATLAB R2023a or later.

解决方案：使用 --matlab-session-mode new 模式，不需要调用 shareMATLABSession()。

Q: MATLAB MCP 服务器启动失败

Error with supplied arguments: invalid MATLAB session mode spawn

解决方案：新版 MCP 服务器已改名，将 spawn 改为 new。

Q: Agentic Toolkit 工具报错

未定义与 'string' 类型的输入参数相对应的函数 'dictionary'

解决方案：这是 R2022a 的兼容性问题，需要升级到 R2022b+。当前可通过 evaluate_matlab_code 直接使用标准 API 替代。

Q: 启动时出现 Connector 日志警告

警告: 执行 'message.internal.Subscription' 类析构函数时，捕获到以下错误:
错误使用 connector.internal.log
Connector 中出现错误: Incorrect argument data types for log.

解决方案：这是无头模式下（headless）的已知问题，不影响功能，可以忽略。

配置的 AGENTS.md 规则

为确保 Codex 始终用中文回答，已在用户目录创建全局 AGENTS.md：

# AGENTS.md

## 语言要求

始终用中文回答所有问题。所有输出、解释、代码注释（除非代码本身是英文的）都使用中文。

该文件位于 C:\Users\<用户名>\AGENTS.md，对所有项目生效。

路径注意事项

Windows 路径在 TOML 配置文件中需要使用单引号（'）来避免反斜杠转义问题：

command = 'C:\Users\haiqiao.huang.o\matlab-mcp-server\matlab-mcp-server-windows-x64.exe'

参考资料

• MATLAB MCP Server
• Simulink Agentic Toolkit
• Codex
• MCP Protocol