用 AI 控制 CODESYS：codesys-mcp-persistent 完整配置指南
如果你是 PLC 工程师，你一定遇到过这样的场景：反复创建相似的 Function Block、手动配置设备参数、在编译错误里来回排查。这些工作本质上是重复劳动。现在，借助 MCP（Model Context Protocol）技术，Claude 可以直接操作 CODESYS IDE，帮你完成这些任务——而你不需要懂任何 AI 开发知识。
目录
-
什么是 CODESYS MCP？ -
市面上有哪几种 CODESYS MCP 方案？ -
为什么选择 codesys-mcp-persistent？ -
安装前你需要准备什么？ -
完整安装步骤（无需 Python） -
在 Claude Code 中注册 MCP -
28 个工具能做什么？ -
Persistent 模式和 Headless 模式的区别 -
常见问题解答 -
总结与建议
什么是 CODESYS MCP？
CODESYS 是全球工业自动化领域使用最广泛的 PLC 开发平台之一，基于 IEC 61131-3 标准，支持 ST、LD、FBD 等多种编程语言。它有一个强大但鲜为人知的功能：Scripting Engine——允许外部程序通过 Python 脚本来驱动 IDE 执行操作，比如创建 POU、编译项目、连接 PLC 设备。
MCP（Model Context Protocol）是 Anthropic 推出的一套开放协议，让 AI 助手能够通过标准化接口调用外部工具。简单来说，CODESYS MCP 就是一座桥：左边连接 Claude（AI），右边连接 CODESYS IDE，让 AI 可以像人一样操作 PLC 开发环境。
你（用自然语言描述需求）
↓
Claude Code（AI 理解意图）
↓
CODESYS MCP Server（翻译成 CODESYS 操作）
↓
CODESYS IDE（执行，界面实时更新）
↓
PLC / SoftPLC 运行时
市面上有哪几种方案？
目前社区里主要有三种 CODESYS MCP 方案，它们在技术路线、功能深度和安装难度上各有不同：
| 方案 | 实现语言 | 工具数量 | 在线操作 | 安装难度 |
|---|---|---|---|---|
codesys-mcp（VS Code 桥接） |
TypeScript | 少 | ❌ | 需要 VS Code |
codesys-mcp-persistent |
TypeScript / Node.js | 28 个 | ✅ | 最低 |
| 官方 CODESYS GmbH MCP | 原生集成 | 较多 | ✅ | 需 SP22 版本 |
第一种方案依赖 VS Code 作为中间层，适合已经在用 VS Code 开发的工程师，但工具集偏少，不支持在线 PLC 操作。
官方方案稳定性最好，但要求 CODESYS 升级到 V3.5 SP22 预览版，很多企业环境无法随意升级生产工具链。
codesys-mcp-persistent 是目前功能覆盖最全的社区方案：纯 Node.js 实现、无需 Python 环境、支持 28 个工具、可以在线连接 PLC 读写变量。
为什么选择这个方案？
1. 不需要 Python 环境
很多工控工程师的电脑上没有 Python，而这个方案用 Node.js 实现，只要你装了 Node.js（大概率已经有了），一条命令搞定安装。
2. CODESYS 界面保持可见
这是 persistent 模式的核心价值。其他方案每次执行命令都会新启动一个 CODESYS 进程，执行完就关掉，你看不到发生了什么。
persistent 模式不同：CODESYS 界面始终打开，AI 做的每一个操作——添加 POU、修改代码、编译——都会实时显示在你面前。你可以随时介入，也可以跟 AI 并行工作。
3. 功能完整，覆盖全开发流程
从新建项目到下载程序到读写变量，28 个工具覆盖了 PLC 开发的完整链路，不需要切换其他工具。
4. 与 @codesys/mcp-toolkit 兼容
如果你之前用过 @codesys/mcp-toolkit，这个方案是直接替代品，工具名称和参数完全兼容，不需要修改已有的工作流。
安装前准备
在开始之前，确认以下环境已就绪：
-
操作系统：Windows（CODESYS 仅支持 Windows） -
CODESYS 版本：V3.5 SP19 或 SP21（安装时需勾选 Scripting Engine 组件） -
Node.js：18.0.0 或更高版本（在终端运行 node --version确认） -
Claude Code CLI：已安装并登录
如果 Node.js 未安装，前往 nodejs.org 下载 LTS 版本，安装过程中保持默认选项即可。
完整安装步骤
第一步：全局安装 codesys-mcp-persistent
打开 PowerShell 或 命令提示符，运行：
npm install -g codesys-mcp-persistent
安装完成后，验证是否成功：
codesys-mcp-persistent --version
如果显示版本号，说明安装成功。
第二步：检测你的 CODESYS 安装信息
运行内置的检测命令：
codesys-mcp-persistent --detect
这条命令会自动扫描 Program Files 和 Program Files (x86) 目录，列出所有已安装的 CODESYS 版本，输出类似：
Found CODESYS installations:
- C:\Program Files\CODESYS 3.5.21.0\CODESYS\Common\CODESYS.exe
Profile: CODESYS V3.5 SP21 Patch 3
把这里的路径和 Profile 名称记下来，下一步配置时要用到。
⚠️ Profile 名称必须完全一致，包括大小写和空格，比如
CODESYS V3.5 SP21 Patch 3。在 CODESYS IDE 中通过 Tools → Options → Environment → Profiles 可以查看准确名称。
第三步：验证工具可以单独运行
在正式接入 Claude Code 之前，先单独测试工具是否能正常启动 CODESYS：
codesys-mcp-persistent `
--codesys-path "C:\Program Files\CODESYS 3.5.21.0\CODESYS\Common\CODESYS.exe" `
--codesys-profile "CODESYS V3.5 SP21 Patch 3" `
--mode persistent `
--verbose
如果 CODESYS 界面弹出，终端显示 ready，说明配置路径正确。
配置 Claude Code
方法一：命令行注册（推荐）
claude mcp add-json "codesys" '{
"command": "codesys-mcp-persistent",
"args": [
"--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
"--codesys-profile", "CODESYS V3.5 SP21 Patch 3",
"--mode", "persistent"
]
}'
注意：在 JSON 字符串里，反斜杠需要写成
\\。
方法二：直接编辑 .mcp.json
在你的项目根目录或用户目录下找到（或创建）.mcp.json 文件，添加：
{
"mcpServers": {
"codesys": {
"command": "codesys-mcp-persistent",
"args": [
"--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
"--codesys-profile", "CODESYS V3.5 SP21 Patch 3",
"--mode", "persistent"
]
}
}
}
验证注册成功
claude mcp list
看到 codesys 状态为连接正常，配置完成。
28 个工具能做什么？
这是 codesys-mcp-persistent 功能最全面的地方。工具按用途分为五类：
管理工具（3 个）
| 工具名 | 用途 |
|---|---|
launch_codesys |
手动启动 CODESYS（配合 --no-auto-launch 使用） |
shutdown_codesys |
关闭持久化的 CODESYS 实例 |
get_codesys_status |
查询当前状态、进程 ID、运行模式 |
项目工具（5 个）
| 工具名 | 用途 |
|---|---|
open_project |
打开已有的 .project 文件 |
create_project |
从标准模板新建项目 |
save_project |
保存当前项目 |
compile_project |
编译主应用，输出结构化错误信息（超时 120s） |
get_compile_messages |
获取上次编译消息，不触发新编译 |
POU / 代码编写工具（11 个）
| 工具名 | 用途 |
|---|---|
create_pou |
创建 Program、Function Block 或 Function |
set_pou_code |
设置声明区和/或实现代码 |
create_property |
在 FB 内创建属性 |
create_method |
在 FB 内创建方法 |
create_dut |
创建数据单元类型（结构体、枚举、联合体、别名） |
create_gvl |
创建全局变量列表 |
create_folder |
在项目树中创建组织文件夹 |
delete_object |
删除任意项目对象 |
rename_object |
重命名任意项目对象 |
get_all_pou_code |
批量读取项目中所有 POU 的代码（超时 120s） |
在线 / 运行时工具（7 个）
这是与其他方案差异最大的部分，支持实时 PLC 交互：
| 工具名 | 用途 |
|---|---|
connect_to_device |
登录 PLC 运行时（需已配置设备/网关） |
disconnect_from_device |
登出 PLC 运行时 |
get_application_state |
查看 PLC 应用是否在运行、停止或异常 |
read_variable |
读取运行中 PLC 的变量值，如 PLC_PRG.bMotorRunning |
write_variable |
向运行中 PLC 写入/强制变量值 |
download_to_device |
下载编译好的程序到 PLC（优先尝试在线更改，超时 120s） |
start_stop_application |
启动或停止 PLC 应用 |
库管理工具（2 个）
| 工具名 | 用途 |
|---|---|
list_project_libraries |
列出项目引用的所有库及版本信息 |
add_library |
添加库引用到项目 |
两种运行模式
Persistent 模式（默认，推荐）
这是这个工具的核心特性。工作原理如下：
-
服务器启动 CODESYS.exe，携带--runscript=watcher.py参数，不加--noUI，所以界面正常显示 -
watcher 脚本在 .NET 后台线程轮询一个 commands/目录，同时把控制权还给 CODESYS，界面保持响应 -
当 Claude 调用某个工具时，服务器将 Python 脚本写入 commands/目录 -
后台线程检测到命令，通过 system.execute_on_primary_thread()在 CODESYS UI 线程上执行 -
结果原子写入 results/目录，返回给 Claude -
AI 操作的效果实时反映在你面前的 IDE 界面里
在命令执行期间（尤其是编译、打开项目这类同步操作），界面会短暂冻结，这是正常现象。
Headless 模式（回退方案）
每次工具调用都会新启动一个带 --noUI 标志的 CODESYS 进程，执行脚本后退出。没有界面，适合服务器环境或 CI/CD 流水线。
当以下情况发生时，会自动切换到此模式：
-
手动指定 --mode headless -
Persistent 模式启动失败，且 --fallback-headless已启用
常见问题解答
Q：安装后找不到 codesys-mcp-persistent 命令怎么办？
A：说明 npm 全局路径不在系统 PATH 里。运行以下命令查看全局安装路径，然后手动添加到环境变量：
npm config get prefix
# 将输出的路径\bin 加入 PATH
Q：--detect 检测不到我的 CODESYS 怎么办？
A：CODESYS 可执行文件通常在这个路径：
C:\Program Files\CODESYS 3.5.XX.X\CODESYS\Common\CODESYS.exe
用文件资源管理器手动找到 CODESYS.exe，把完整路径复制到 --codesys-path 参数里。
Q：Watcher 超时（60 秒内没有就绪信号）怎么排查？
A：按顺序检查以下几点：
-
CODESYS 路径和 Profile 名称是否完全正确 -
CODESYS 启动时是否弹出了模态对话框（比如许可证提示） -
加上 --verbose参数重新运行，查看详细日志
Q：在线工具（connect_to_device、read_variable 等）失败？
A：在线工具有三个前提条件：
-
CODESYS 项目中已配置好设备和网关 -
项目已经成功编译 -
PLC 或 SoftPLC 运行时可以从当前机器访问到
Q：命令超时怎么办？
A：默认超时是 60 秒，编译和下载操作是 120 秒。如果你的项目很大，可以通过 --timeout <毫秒数> 参数延长超时时间：
codesys-mcp-persistent --timeout 300000 ...
同时查看 CODESYS 消息窗口，确认是否有模态对话框或错误阻塞了执行。
Q：项目文件被锁定打不开？
A：另一个 CODESYS 实例可能已经打开了这个项目。先关闭那个实例，或者使用 persistent 模式（保证只有一个 CODESYS 进程在运行）。
实际使用示例
配置完成后，在 Claude Code 会话里，你可以这样描述需求：
帮我创建一个电机控制的 Function Block：
- 名称：FB_MotorControl
- 输入：bStart(BOOL), bStop(BOOL), rSpeedSetpoint(REAL)
- 输出：bRunning(BOOL), bFault(BOOL)
- 实现简单的启停逻辑和故障检测
Claude 会自动调用 create_pou 和 set_pou_code 工具，在你眼前的 CODESYS IDE 里创建并填入代码，然后调用 compile_project 验证语法。
或者：
读取 PLC_PRG.rActualSpeed 当前值，如果超过 1500，把 PLC_PRG.bOverspeed 写入 TRUE
Claude 会依次调用 read_variable 和 write_variable，完成条件判断和写入。
支持的 CLI 参数一览
| 参数 | 说明 | 默认值 |
|---|---|---|
-p, --codesys-path |
CODESYS 可执行文件路径 | 环境变量 CODESYS_PATH 或自动检测 |
-f, --codesys-profile |
CODESYS Profile 名称 | 环境变量 CODESYS_PROFILE 或 CODESYS V3.5 SP21 |
-w, --workspace |
相对路径的工作目录 | 当前目录 |
-m, --mode |
persistent（有界面）或 headless（无界面） |
persistent |
--no-auto-launch |
不在启动时自动打开 CODESYS | 默认自动启动 |
--fallback-headless |
Persistent 失败时自动回退到 Headless | true |
--keep-alive |
服务器停止后保持 CODESYS 运行 | false |
--timeout |
默认命令超时（毫秒） | 60000 |
--detect |
列出已安装的 CODESYS 版本并退出 | — |
--verbose |
启用详细日志 | — |
--debug |
启用调试日志 | — |
也可以通过环境变量设置默认路径，避免每次都写长参数：
$env:CODESYS_PATH = "C:\Program Files\CODESYS 3.5.21.0\CODESYS\Common\CODESYS.exe"
$env:CODESYS_PROFILE = "CODESYS V3.5 SP21 Patch 3"
总结与建议
codesys-mcp-persistent 是目前社区里功能最完整的 CODESYS × AI 集成方案，适合以下场景：
-
想用 AI 加速 PLC 代码编写，减少重复劳动 -
需要批量操作项目结构（创建多个 POU、GVL、DUT） -
调试阶段需要频繁读写 PLC 变量 -
团队想要标准化项目结构，用 AI 生成符合规范的代码模板
整个安装过程只需要三步：npm install -g codesys-mcp-persistent → --detect 查询安装信息 → claude mcp add-json 注册配置。没有 Python、没有复杂依赖、没有额外中间件。
唯一需要注意的是：CODESYS 安装时必须包含 Scripting Engine 组件，这是所有 MCP 方案的底层依赖。如果你安装时没有选这个组件，需要重新运行安装程序，勾选后修复安装。
本文基于 codesys-mcp-persistent 开源项目文档整理，项目地址：github.com/luke-harriman/Codesys-MCP，协议：MIT。
