使用说明

codesys mcp持久化

MCP服务器，将CODESYS V3.5 IDE脚本API公开为41个工具和3个资源，CODESYS UI通过基于文件的IPC观察器在调用之间保持打开。

与生成新的无头包装不同 --noUI CODESYS处理每个命令，此服务器启动CODESYS，其UI可见，并通过在同一实例中运行的观察者脚本路由每个工具调用。IDE中会实时显示更改，用户可以与CODESYS以及AI驱动的自动化进行交互。

需求

视窗
Node.js 18+
CODESYS V3.5 SP19或SP20 用于持久模式。 SP21+仅在无头模式下运行 --看已知限制.

安装

git clone <repository-url>
cd Codesys-MCP
npm install
npm run build
npm link

配置

.mcp.json （克劳德代码）：

{
  "mcpServers": {
    "codesys": {
      "command": "codesys-mcp-persistent",
      "args": [
        "--codesys-path", "C:\\Program Files\\CODESYS 3.5.20.0\\CODESYS\\Common\\CODESYS.exe",
        "--codesys-profile", "CODESYS V3.5 SP20",
        "--mode", "persistent"
      ]
    }
  }
}

对于SP21+，设置 --mode headless （每个工具调用都会生成一个 --noUI CODESYS过程）。

命令行界面

标志	描述	默认值
`-p, --codesys-path <path>`	通往 `CODESYS.exe`	`$CODESYS_PATH` 或 `C:\Program Files\CODESYS 3.5.21.0\CODESYS\Common\CODESYS.exe`
`-f, --codesys-profile <name>`	CODESYS配置文件名称	`$CODESYS_PROFILE` 或 `CODESYS V3.5 SP21`
`-w, --workspace <dir>`	相对路径工作区	cwd
`-m, --mode <mode>`	`persistent` 或 `headless`	`persistent`
`--no-auto-launch`	启动时不要启动CODESYS	自动启动
`--fallback-headless`	如果持续启动失败，则退回到无头模式	`true`
`--keep-alive`	服务器停止后保持CODESYS运行	`false`
`--kill-existing-codesys`	杀死任何跑步者 `CODESYS.exe` 发射前	`false`
`--timeout <ms>`	默认命令超时	`60000`
`--detect`	列出已安装的CODESYS版本并退出	-
`--verbose` / `--debug`	日志记录	-

环境变量：

CODESYS_PATH, CODESYS_PROFILE --对应标志的默认值
CODESYS_MCP_READY_TIMEOUT_MS --观察者就绪截止日期（默认值 180000)

工具

管理

工具	说明
`launch_codesys`	手动启动CODESYS（与 `--no-auto-launch`).如果存在实时会话，则采用该会话
`shutdown_codesys`	关闭持久CODESYS实例
`get_codesys_status`	报告状态、PID、执行模式
`eval_python`	[DEV] 对live执行任意IronPython 2.7 `scriptengine`代码必须 `print("SCRIPT_SUCCESS")` 退出前

项目

工具	说明
`open_project`	打开现有 `.project` 文件
`create_project`	创建一个新项目。默认复制已安装的CODESYS `Standard.project`；通行证 `templatePath` 复制特定 `.project`，或 `templateName` 实例化在CODESYS的模板管理器中注册的模板
`list_project_templates`	从CODESYS的模板管理器中枚举模板 `%ProgramData%/CODESYS`
`save_project`	保存当前打开的项目
`compile_project`	使用结构化错误输出进行构建（超时120秒）
`get_compile_messages`	检索最后的编译器消息，而无需重新生成

POU/代码编写

工具	说明
`create_pou`	创建程序、功能块或函数
`set_pou_code`	设置声明和/或实现。接受方法/属性路径(`Application/MyFB/Method1`).自动保存到磁盘
`create_property` / `create_method`	向功能块添加属性/方法
`create_dut`	创建数据单元类型（结构、枚举、联合、别名）
`create_gvl`	创建全局变量列表，可选地使用初始声明
`create_folder`	创建组织文件夹
`delete_object`	删除用户创建的对象。拒绝系统节点(`Application`, `Device`, `Library Manager`等）和顶级路径
`rename_object`	重命名任何项目对象
`get_all_pou_code`	批量读取项目中的每个声明+实现（超时120秒）
`search_code`	在每个文本POU/Method/Property/DUT/GVL主体中搜索正则表达式或文字子字符串
`find_references`	符号的单词边界搜索；包裹 `search_code`
`rename_symbol`	对所有POU主体进行文本重命名。两阶段计划+申请； `dryRun=true` 默认情况下

在线/运行时

工具	说明
`connect_to_device`	登录到PLC运行时。可选通过 `ipAddress` （以及 `gatewayName`，默认值 `Gateway-1`)；设置设备地址，然后在登录前将其从IP形式重新解析为网关扫描节点形式
`disconnect_from_device`	注销。如果未连接，则无操作
`set_credentials`	为后续登录设置默认用户名/密码。用户名必须非空
`set_simulation_mode`	切换设备级模拟模式
`get_application_state`	报告运行/停止/异常以及登录状态
`read_variable`	读取实时变量。路径： `GVL.var` / `PRG.var` / `GVL.s.aRoi[0].field` （没有 `Application.` 前缀）
`write_variable`	通过写 `set_prepared_value` + `force_prepared_values`。变量为强制，直到非强制或运行时重新启动
`download_to_device`	下载已编译的应用程序。 `mode`: `auto` （默认）， `online_change`，或 `full`。启动登录后创建的应用程序。120秒超时
`start_stop_application`	启动或停止PLC应用程序
`monitor_variables`	以固定间隔对一个或多个变量进行采样。持续时间上限为60秒， `intervalMs` 地板10ms

在线工具路由 scriptengine.online 通过电话 ExecuteSource 通过框架 with_executor 助手在 ensure_online_connection.py没有它， create_online_application 提高 InvalidOperationException: Stack empty 来自真实PLC上的IPC驱动脚本。

图书馆管理

工具	说明
`list_project_libraries`	列出包含版本信息的引用库
`add_library`	添加库引用。从库管理器UI传递完全限定的占位符字符串（例如。 `Standard, * (System)`)--赤裸裸的名字，比如 `Util` 不会解决

设备树

工具	说明
`list_device_repository`	枚举本地CODESYS设备存储库中的设备描述符。可选的 `vendor`, `nameContains`, `maxResults` 过滤器
`inspect_device_node`	设备节点的只读自检：描述符元数据、带值的参数、子设备
`add_device`	包裹 `parent.add_device(name, type, id, version)`.搭配 `list_device_repository` 获取规范id
`set_device_parameter`	实验。许多现场总线参数仅为GUI，并返回明确的错误
`map_io_channel`	将现场总线I/O通道绑定（或清除）到全局变量。按名称路径解析的通道(`Inputs/Byte 0/Bit 3`)或数字索引(`0/3`)

归档

工具	说明
`create_project_archive`	将打开的项目另存为 `.projectarchive`。首先保存未保存的编辑

资源

URI	描述
`codesys://project/status`	脚本状态和打开的项目信息
`codesys://project/{path}/structure`	项目树
`codesys://project/{path}/pou/{pou}/code`	POU/方法/属性声明+实现

{path} 和 {pou} 使用 RFC 6570保留扩展 --使用raw传递值 : 和 /, 不百分比编码。在Windows上，使用正斜杠：

codesys://project/C:/Users/me/Documents/MyPLC.project/structure
codesys://project/C:/Users/me/Documents/MyPLC.project/pou/Application/MyFB/Method1/code

这两个模板化资源未出现在 ListMcpResourcesTool （仅限 project-status 是静态的）。

⚠️ 如果请求的项目路径与当前打开的项目不同，资源处理程序将拒绝切换——它将引发上下文，而不是静默地交换上下文。

执行模式

持久（默认）。 启动时，服务器扫描 %TEMP%/codesys-mcp-persistent/ 对于前一个MCP服务器留下的实时会话（匹配配置文件、PID活动等）， ready.signal 现在）并采用它。否则，它就会滋生 CODESYS.exe --runscript=watcher.py （没有 --noUI).观察者写道 ready.signal，然后运行一个后台线程来轮询 commands/ 目录，并通过以下方式将每个脚本封送到CODESYS UI线程上 system.execute_on_primary_thread().结果登陆 results/；具有指数退避的节点轮询（100ms→ 1s).UI在命令之间保持交互，并在同步API调用（编译、打开）期间短暂暂停。

无头。 每次工具调用都会生成一个新的 --noUI CODESYS进程，运行脚本并退出。没有UI。在以下情况下使用 --mode headless 设置，当 --no-auto-launch 使用和 launch_codesys 未被调用，或者当持续启动失败时 --fallback-headless 打开。

检测安装

codesys-mcp-persistent --detect

扫描 Program Files 和 Program Files (x86) 用于CODESYS安装。

已知限制

CODESYS V3.5 SP21+上的持久模式已中断。 CODESYS已删除 se.system.execute_on_primary_thread() 从脚本API中的SP21行中的某个位置。持续启动完成(ready.signal 触发），然后每次工具调用都会返回 Marshal error: The functionality 'system.execute_on_primary_thread(...)' is no longer supported. --fallback-headless 仅为发射时间，不捕捉此信息。解决方法：（a）与 --mode headless（b）使用以下远期港口 phobidotno/Codesys-MCP-SP21-plusSP19/SP20不受影响。
set_pou_code 自动保存到磁盘 每一个成功的电话。UI Ctrl+Z无法恢复之前的内容。
set_pou_code 空字符串是不允许的。 经过 declarationCode: "" 或 implementationCode: "" 保持该部分不变。要清除一个部分，请传递一个单行占位符（例如。 // cleared).
delete_object 拒绝系统节点和任何顶级对象 （没有 /).系统保留的精确路径： Application, Device, Project Settings, Device/Plc Logic, Application/Library Manager, Application/Task Configuration, Application/Task Configuration/MainTask, Device/Communication, Device/Communication/Ethernet, Device/SoftMotion General Axis Pool （以及 Device/Plc Logic/... 变体）。
set_credentials 拒绝空用户名。 对于无身份验证运行时，根本不要调用此工具。
add_library 需要一个完全限定的占位符 匹配库管理器UI字符串（例如。 Standard, * (System)).裸名失败 placeholder library X could not be resolved.
DUT名称包含 . 被CODESYS拒绝 (The name 'X.Y' is not valid for this object).
标识符长度在创建时不强制执行。 CODESYS只在编译/保存时抱怨。坚持使用≤32个字符的IEC标识符。
find_object_by_path 拒绝不明确的匹配 并返回 None.走一条更具体的路。
is_simulation_mode getter返回 None 在某些设备描述符上。设定者工作；通过编译+登录进行验证。

故障排除

未找到CODESYS --验证 --detect可执行文件通常位于 C:\Program Files\CODESYS 3.5.XX.X\CODESYS\Common\CODESYS.exe.

每次工具调用都会返回 Marshal error: ... is no longer supported --您正在使用SP21+。重新启动 --mode headless.

监视器超时 --默认值为180秒。旧SP的冷启动可能会超过60年代的预算。在慢速硬件上进一步颠簸： CODESYS_MCP_READY_TIMEOUT_MS=300000。如果CODESYS仍在运行，请致电 launch_codesys 同样，启动器将重新附加到活动PID，而不是生成第二个实例。

命令超时 --默认60秒； compile_project, get_all_pou_code，以及 download_to_device 使用120秒。增加 --timeout <ms>.

MCP重启时项目文件被锁定 --启动器在启动时采用来自先前服务器的实时会话。如果你仍然打 StandardError: The selected project is currently in use，杀死孤儿 CODESYS.exe 通过任务管理器或pass --kill-existing-codesys 下次启动时（默认情况下关闭以保护外部IDE会话）。

在线工具故障 --它们需要配置设备/网关（或 connect_to_device(ipAddress=...)，或 set_simulation_mode(enable=true))，编译成功，PLC可访问。

Network error: No route to host 从 connect_to_device 尽管 ping works——通过网关扫描节点地址进行V3登录路由（例如。 0301.B0F7)，不是通过IP编码形式(0192.0168.0083.0247)那个 set_gateway_and_address 从原始IP存储。 connect_to_device 登录前重新扫描并重置地址；如果它仍然失败，则运行时端口（默认为TCP 11740）的网关可能会被阻止。

发展

npm install
npm run build      # tsc + copy src/scripts/ -> dist/scripts/
npm test
npm run typecheck
pwsh dev/check-scripts.ps1   # ASCII + template-reference static checks

项目布局：

src/
  bin.ts              CLI entry point
  server.ts           MCP tool / resource registration
  launcher.ts         CODESYS process management + session adoption
  ipc.ts              File-based IPC transport
  headless.ts         Headless fallback executor
  script-manager.ts   Python template loading + interpolation
  executor-proxy.ts   Race-free executor swap during background auto-launch
  result-parser.ts    RESULT_JSON marker extraction
  scripts/            IronPython 2.7 watcher + helpers + tool scripts
tests/
  unit/               IPC, script manager, launcher
  integration/        Script pipeline + manual CODESYS tests

许可证

麻省理工学院

使用说明

codesys mcp持久化

需求

安装

配置

命令行界面

工具

管理

项目

POU/代码编写

在线/运行时

图书馆管理

设备树

归档

资源

执行模式

检测安装

已知限制

故障排除

发展

许可证

相关 MCP

串口AI控制工具

TCP套接字MCP服务器

CODESYS MCP工具包

Ignition MCP 服务器

制造维护协议服务器

自动化项目交互服务器