Skip to content
Back to search

codesys-mcp-toolkit

Model Context Protocol server for CODESYS automation platform

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/johannesPettersson80/codesys-mcp-toolkit with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/johannesPettersson80/codesys-mcp-toolkit'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/johannespettersson80--codesys-mcp-toolkit/badge.svg)](/listings/johannespettersson80--codesys-mcp-toolkit)

HTML

<a href="/listings/johannespettersson80--codesys-mcp-toolkit"><img src="/api/listings/johannespettersson80--codesys-mcp-toolkit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The recommended way to install is globally using npm:

npm install -g @codesys/mcp-toolkit

This installs the package globally, making the `codesys-mcp-tool` command available in your system's terminal PATH.

*(Advanced users can also install from source for development - see CONTRIBUTING.md if available).*

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 573 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # CODESYS MCP Toolkit
  3. **Let Claude, or any MCP client, read, write, compile and simulate Structured Text in your CODESYS V3.5 projects.**
  4. English | [简体中文](README.zh-CN.md)
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
  6. [![npm](https://img.shields.io/npm/v/@codesys/mcp-toolkit)](https://www.npmjs.com/package/@codesys/mcp-toolkit)
  7. ![CODESYS V3.5](https://img.shields.io/badge/CODESYS-V3.5-c8102e)
  8. ![Node.js 20 or later](https://img.shields.io/badge/node-%E2%89%A520-339933)
  9. ![Platform: Windows](https://img.shields.io/badge/platform-Windows-0078d4)
  10. [![Model Context Protocol](https://img.shields.io/badge/MCP-server-6e56cf)](https://modelcontextprotocol.io)
  11. </div>
  12. An [MCP](https://modelcontextprotocol.io) server that keeps one CODESYS session
  13. open in the background and gives Claude, or any MCP client, direct access to
  14. it. Claude works on your real project with the real CODESYS compiler, and you
  15. can watch the code change as it happens.
  16. ![Claude builds a tank level controller in CODESYS: the live panel in the chat, the code compiled with 0 errors and five simulation tests passed, and the same function block in the CODESYS-style workspace, ready to review](docs/images/claude-and-codesys.png)
  17. ## Highlights
  18. - **Edits your real project.** POUs, methods, properties, interfaces, DUTs and
  19. GVLs, as Structured Text.
  20. - **Compiles with the real compiler.** Errors come back with object, line and
  21. code, including in code that no task calls yet.
  22. - **Tests in simulation.** Run, step exact cycles, read, write and force values
  23. in CODESYS's own simulation, with nothing else to install.
  24. - **Understands the project.** Outlines, I/O lists, the device tree and library
  25. interfaces, without reading every object.
  26. - **Shows its work.** A live panel with the project tree, the code as it is
  27. written, compile results, and Accept or Revert for each change.
  28. - **Designs operator screens.** Claude builds a live HMI for your program:
  29. an overview of the line's stations, process diagrams with ISO 10628-2
  30. symbols and ISA-5.1 instruments, clear state signs, values, trends and
  31. alarms. It looks at the result and polishes it. You operate it in the
  32. browser against the simulation, it exports as a native CODESYS
  33. visualization with real CODESYS alarms, and as a P&ID sheet for the
  34. documentation.
  35. - **Ready for handover.** A project report with a commissioning checklist
  36. built from the project, and a plain-text export of every object for git.
  37. - **Never touches a real controller.** The only online connection is to
  38. CODESYS's own simulation, and every online call checks for it first.
  39. ## Quick start
  40. ### Requirements
  41. - Windows with **CODESYS V3.5** and its **Scripting** add-on. Tested with SP21
  42. and SP22 on Scripting 4.2, and SP21 on 4.1. SP16 and later should work.
  43. - **Node.js 20** or later.
  44. Schneider EcoStruxure Machine Expert V2.3 (`LogicBuilder.exe`, Scripting 4.1)
  45. works too: pass `--codesys-path` and leave out `--codesys-profile`, since Machine
  46. Expert has no profiles. See the [Machine Expert notes](docs/machine-expert-testing.md).
  47. ### Install
  48. ```bash
  49. npm install -g @codesys/mcp-toolkit
  50. ```
  51. Coming from version 1? The tools have changed: see
  52. [Migrating from v1](#migrating-from-v1).
  53. ### Connect it to Claude Desktop
  54. Add the server to `%APPDATA%\Claude\claude_desktop_config.json`, then restart
  55. Claude Desktop:
  56. ```json
  57. {
  58. "mcpServers": {
  59. "codesys": {
  60. "command": "codesys-mcp-tool",
  61. "args": [
  62. "--codesys-path", "C:\\Program Files\\CODESYS 3.5.21.0\\CODESYS\\Common\\CODESYS.exe",
  63. "--codesys-profile", "CODESYS V3.5 SP21",
  64. "--workspace", "C:\\PLC\\Projects"
  65. ]
  66. }
  67. }
  68. }
  69. ```
  70. `--codesys-path` and `--codesys-profile` are optional. Without them the server
  71. uses the newest CODESYS install under Program Files and its newest profile.
  72. Using OpenCode, Cursor, Cline or another client, or a model such as DeepSeek or
  73. Qwen? See [Other clients and models](#other-clients-and-models).
  74. ### Try it
  75. > Create a project called `BlinkDemo.project`. Add a function block that toggles
  76. > an output once per second, call it from `PLC_PRG`, compile it, and prove in
  77. > simulation that the output toggles.
  78. CODESYS starts in the background when the server launches. A cold start takes
  79. 1 to 3 minutes; later starts take about 10 seconds.
  80. Claude Desktop asks for approval per tool. Choose **Always allow** the first
  81. time it asks about `codesys`, and once more for `open_sim_panel`. After that it
  82. doesn't ask again.
  83. ## What Claude can do
  84. Everything goes through one MCP tool, `codesys`, with an action for each
  85. operation. [The reference](docs/reference.md) describes each one.
  86. | Area | Actions |
  87. | --- | --- |
  88. | **Projects** | `open_project` `create_project` `save_project` `close_project` `codesys_status` |
  89. | **Read code** | `get_project_tree` `read_objects` `search_code` `get_outline` |
  90. | **Change code** | `write_object` `create_object` `create_graphical` `delete_object` `rename_object` |
  91. | **Build** | `compile` |
  92. | **Libraries** | `find_library` `list_libraries` `add_library` `pin_library` `remove_library` `get_library_api` `get_signature` |
  93. | **Navigate code** | `find_references` `rename_symbol` |
  94. | **Tasks and I/O** | `list_tasks` `configure_task` `get_io_list` `get_devices` `find_device` `add_device` `device_parameters` `configure_device` |
  95. | **Change tracking** | `checkpoint` `get_changes` `revert_object` |
  96. | **Simulation** | `codesys_sim_start` `codesys_sim_stop` `codesys_sim_status` `codesys_sim_control` `codesys_sim_cycle` `codesys_sim_read` `codesys_sim_write` `codesys_sim_force` `codesys_sim_unforce` `codesys_sim_test` |
  97. | **Trace** | `trace_setup` `trace_record` |
  98. | **Debug** | `breakpoint_set` `breakpoint_on_change` `breakpoint_clear` `debug_status` `debug_step` `debug_continue` `watch` |
  99. | **HMI screens** | `hmi_save_screen` `hmi_template` `hmi_screenshot` `hmi_export_codesys` `hmi_list` `hmi_delete_screen` `open_hmi` `hmi_save_symbol` `hmi_symbols` `hmi_delete_symbol` `hmi_translate` `hmi_pid` |
  100. | **Alarms** | `alarm_list` `alarm_status` `alarm_acknowledge` `alarm_history` `create_alarm_history` |
  101. | **Handover** | `project_report` `export_sources` `compare_sources` `create_recipes` |
  102. | **Helpers** | `batch` `wait` `help` `open_workspace` `show_in_codesys` |
  103. `batch` runs up to 50 actions in one call, which is much faster than separate
  104. calls.
  105. Some actions go beyond what CODESYS's scripting API documents and use CODESYS's
  106. own services inside the IDE: `get_signature`, `find_references`,
  107. `rename_symbol`, `trace_setup`, `trace_record`, the debug actions,
  108. `hmi_export_codesys` (with its alarms and user groups), the alarm actions and
  109. `--show-window`.
  110. They are **experimental**: checked on CODESYS V3.5 SP21 and SP22 as noted in
  111. the [changelog](CHANGELOG.md). On another version they may report that the
  112. feature isn't available, or not work. They don't depend on CODESYS's
  113. language: the native HMI export was checked with a German and a Chinese user
  114. interface too.
  115. Claude writes Structured Text, and creates ladder (LD), FBD, CFC and SFC
  116. programs and function blocks with `create_graphical` from a simple description
  117. of rungs, networks or steps; CODESYS draws them. SFC charts can have alternative
  118. and parallel branches and jumps. Reading an LD, FBD, CFC or SFC POU gives the
  119. same description, so Claude can change existing graphical code too: it edits the
  120. description and sends it back with `replace: true`.
  121. ## Live panel
  122. Right after opening or creating a project, Claude opens the panel as a card in
  123. the chat. It shows the status, the object Claude is working on and how many
  124. objects changed. **Open workspace** expands it into a CODESYS-style view with
  125. the project tree, editor tabs, compile problems and a review list.
  126. From the panel you can **Accept** or **Revert** each change, compare it with
  127. the version you last reviewed, and **Pause Claude** while you look around.
  128. ![The workspace: a PI controller function block with properties and an interface, changed by Claude and waiting for review](docs/images/workspace.png)
  129. The card needs a client that supports
  130. [MCP Apps](https://modelcontextprotocol.io/extensions/apps). In our testing
  131. Claude Desktop draws it in the Code tab but not in a normal chat
  132. ([anthropics/claude-ai-mcp#1243](https://github.com/anthropics/claude-ai-mcp/issues/1243)).
  133. Ask Claude to open the workspace in your browser if you'd rather have it there;
  134. the browser never opens by itself.
  135. [More about the panel](docs/reference.md#live-panel)
  136. ## HMI screens
  137. Ask Claude for operator screens and it designs them for your program: an
  138. overview of the line's stations, process diagrams, values with their
  139. set-points, trends and alarms, all bound to your PLC variables. The look is a
  140. calm, flat design system (Siemens iX colours, high-performance HMI practice
  141. after ISA-101): colour means a state or something to act on, never decoration.
  142. ![The overview of a heat treatment line: the machine's state "Production" in the top bar's corner with a green line under the bar, the line as station tiles on a product path (feed tank, pump, filter, heating with steam joining from above, holding tank, pump, centrifuge, filling) each with its pictogram and key value, a play sign before the running pumps and the centrifuge, a hand on the steam valve in manual, and below them cards for the outlet temperature, its setpoint, the tank levels and the alarms; Manual/Auto and Reset, Start, Stop along the bottom](docs/images/hmi-overview.png)
  143. - **The machine in the frame.** Its state (Production, Fault, Stopped, ...)
  144. sits in the top bar's corner with a thin line in its colour under the bar;
  145. Start, Stop, Reset and the Manual/Auto switch in a bar along the bottom; the
  146. active faults, warnings and messages counted in the top bar; the pages in a
  147. rail on the left. `hmi_template` gives Claude a good layout for each kind of
  148. page. Panels: 1280x720, 1920x1080, 1024x768 or 800x480.
  149. - **An overview of the stations.** A `line` card draws the process as station
  150. tiles on a product path, each with its pictogram, key value and state; a
  151. supply such as steam joins its station from above, and tapping a tile opens
  152. its page.
  153. - **Process diagrams to the standards.** Symbols drawn from ISO 10628-2 (pumps,
  154. fans, valves, check and control valves, heat exchangers, motors on the
  155. machine they drive, agitators, separators, filters, conveyors and more),
  156. instruments as ISA-5.1 bubbles outside the vessel and joined to where they
  157. measure, and pipes that route themselves between named ports
  158. (`T-201.right`, `P-201.in`) with line names and flow arrows at the edges.
  159. - **State at a glance, without clutter.** Three separate things, each with its
  160. own sign, so none hides another: the run state before the name (▶ running,
  161. ■ stopped), the mode after it (a hand in Manual; Auto shows nothing) and the
  162. condition at the symbol's corner (an amber warning or a red alarm; OK shows
  163. nothing). A tripped switch (LSH, PSL) gets the same badge at its bubble. A
  164. closed valve is drawn filled, as on a P&ID. Symbols are never
  165. filled grey or coloured by state, and nothing moves.
  166. - **Labels place themselves.** Every name, line name and reading is put where
  167. it touches no pipe, equipment or other text and stays inside the card; a
  168. tank's name goes inside the vessel. A value that belongs to a piece of
  169. equipment, such as a control valve's opening, is shown under its name.
  170. - **Claude checks its own work.** Saving a screen checks the layout (overlaps,
  171. labels without room) and that the diagram is a process: equipment no pipe
  172. reaches, an inlet without an outlet, a heat exchanger with one circuit,
  173. instruments inside a vessel, a motor that drives nothing, a reading drawn
  174. as a separate sensor when it belongs to equipment, or a run state on a
  175. filter. `hmi_screenshot` returns the screen as an image to look at.
  176. - **Your own symbols.** Claude can draw a symbol you need as SVG, or import
  177. yours from an SVG file (`hmi_save_symbol`), and gets back a picture of it
  178. with its ports. Custom SVG is checked against a short list of elements and
  179. attributes: scripts, styles, links and external images are refused.
  180. - **Live in your browser.** Ask Claude to open the HMI (`open_hmi`). The page
  181. is served by the toolkit on 127.0.0.1 with a token, like the workspace.
  182. While CODESYS's simulation runs it shows live values and trends, and
  183. buttons, switches and setpoints write to the simulation, so you can operate
  184. your program before any hardware exists.
  185. - **Light, dark and high-contrast themes,** the same on every page; `accent`
  186. puts your company colour on the highlights, and text on it turns black or
  187. white to stay readable. Screens are saved next to the project as
  188. `<project>.hmi.json`, so they travel with it and can go into version
  189. control.
  190. ![The heat treatment process: feed into tank T-201 with a high level switch LSH-201, pump P-201 with a low pressure switch PSL-201 on its outlet, filter F-201 with an amber warning (clogged), heat exchanger E-201 heated by steam through control valve TCV-201 (in manual, 46 % open) with the condensate returned, the outlet temperature TT-201 on the line controlling the valve, tank T-202 with its agitator, pump P-202 feeding centrifuge C-202 with motor M-202 on it, and the product out to filling; running equipment has a play sign before its name](docs/images/hmi-process.png)
  191. ![The same process page in the dark theme](docs/images/hmi-process-dark.png)
  192. ![The standard process symbols with their ports, and the valves open and closed](docs/images/hmi-symbols.png)
  193. The HMI writes only into CODESYS's own simulation, like the rest of the
  194. toolkit. Screenshots use Microsoft Edge or Google Chrome, whichever is
  195. installed.
  196. ### P&ID sheet
  197. `hmi_pid` exports a screen's process diagram as an engineering P&ID drawing
  198. for documentation and commissioning: the same diagram drawn black on white,
  199. with nothing live, on an A3 sheet with a frame, a legend of the symbols it
  200. uses and a title block (drawing number, revision, date). It is saved next to
  201. the project as PDF, SVG or PNG. Since it comes from the HMI's own diagram,
  202. there is no second drawing to keep up to date.
  203. ![The heat treatment line as an A3 P&ID: the diagram in black on white with its tags, instruments and line names, a legend of the symbols used (vessel, centrifugal pump, filter, control valve, heat exchanger, agitator, separator, motor, instrument, process line, signal line) and a title block](docs/images/hmi-pid.png)
  204. ### As a native CODESYS visualization
  205. `hmi_export_codesys` builds the same screens as real CODESYS visualizations in
  206. your project. They are ordinary visualization objects, so they go with the
  207. application like ones you drew yourself (checked in CODESYS's simulation, not
  208. on a controller): the same frame, cards, symbols, state signs, labels and
  209. station tiles as in the browser, drawn with CODESYS's own elements and
  210. pictures in an embedded image pool. A generated program, `PRG_HMI_<screen>`,
  211. works out what the pictures need (scaled bars and levels, the machine state,
  212. alarm counts). Claude gets a picture of the result.
  213. ![The overview as a native CODESYS visualization in the simulation: the same station tiles, signs, cards and frame as in the browser, with the active filter warning in the alarms card](docs/images/hmi-codesys-overview.png)
  214. ![The heat treatment process as a native CODESYS visualization in the simulation](docs/images/hmi-codesys-process.png)
  215. A multi-page HMI comes out as one visualization per page with the rail of
  216. page buttons, the first page as the start page of TargetVisu and WebVisu at
  217. the panel size, faceplates as CODESYS dialogs, the pages' alarms in CODESYS's
  218. alarm management (Alarm Configuration, with timestamps and acknowledge in the
  219. PLC), and user groups (Operator, Maintenance, Admin) behind a Login button.
  220. Users and passwords are yours to add in the Visualization Manager.
  221. A tile can be limited to a group and up: `access: {min: 'Maintenance'}` lets
  222. lower groups see it without operating it, `below: 'hide'` hides it from them.
  223. The rights go on CODESYS's own elements and also apply when nobody is logged
  224. in.
  225. The alarms are CODESYS's own, not a copy in the HMI: an alarm group with its
  226. observations, classes and messages, which CODESYS's alarm manager evaluates in
  227. the PLC. In the simulation, raising the fault made the group report an active
  228. alarm, and it stayed pending after the fault cleared, until acknowledged, as an
  229. Error-class alarm should.
  230. ![The exported alarms in CODESYS's alarm group editor: a digital observation on PLC_PRG.xHighLevel with class Warning and message "High level T-101 (above 90 %)", and one on PLC_PRG.xFault with class Error and message "Pump P-101 fault"](docs/images/codesys-alarms.png)
  231. Claude can test them in the simulation: `alarm_status` reads each alarm's
  232. state from CODESYS's alarm manager (normal, active, active acknowledged,
  233. cleared but waiting for confirmation or acknowledgement), and
  234. `alarm_acknowledge` acknowledges as an operator would. In the browser HMI and
  235. in CODESYS, an alarm row stays until it is acknowledged, with the time it
  236. came, its state and an acknowledge button.
  237. CODESYS's runtime alarm forgets its times once it is normal again, so the
  238. export also adds an alarm history to the PLC: generated ST that records every
  239. state change of every alarm (with CODESYS's own time of the change) in a
  240. RETAIN ring buffer. `alarm_history` lists it, and an alarms tile with
  241. `history: 5` shows the last events, in the browser and in CODESYS
  242. (`create_alarm_history` adds the same to a project with alarms of its own).
  243. Gauges are the same arc gauge as in the browser (pictures in the image pool,
  244. one per 2.5 % of the range), not CODESYS's chrome meter. Trends show their
  245. current values: a CODESYS trend needs a trend recording that scripting can't
  246. create yet. Checked on CODESYS V3.5 SP21 in the simulation. A visualization
  247. needs the `FloatingPointUtils` library in CODESYS's library repository; if
  248. it's missing, the export says so before it builds anything. A long export
  249. reports its progress (each page, the alarms, the compile) to clients that
  250. show MCP progress.
  251. ## Handover and version control
  252. `project_report` writes a Markdown report next to the project for whoever
  253. commissions or takes over the machine: a summary, the tasks, the I/O list and
  254. device-tree mappings, the CODESYS alarms, the HMI pages, libraries, devices and
  255. the program structure. It ends with a commissioning checklist built from the
  256. project itself: every task's cycle time, every input and output, every mapped
  257. channel, every alarm, every HMI page and the persistent variables to check on
  258. the real machine, plus the safety and archiving items no checklist should
  259. skip. Everything Claude did was tested in CODESYS's simulation only, and the
  260. report says so.
  261. `export_sources` writes the project as plain text for git: one `.st` file per
  262. POU, method, property, action, DUT, GVL and interface, in folders like the
  263. project tree, ladder/FBD/SFC bodies as PLCopenXML, a `project.txt` with tasks,
  264. libraries, devices and alarms, and the HMI screens. A `.project` file is
  265. binary; this folder is what makes a change reviewable as a diff. Exporting
  266. again rewrites only what changed and removes the files of deleted objects.
  267. `compare_sources` compares the open project with such a folder or with another
  268. `.project` file: the objects only in one of them, and a line diff of each
  269. changed one.
  270. ## Other clients and models
  271. The server works with any MCP client, not only Claude. For
  272. [OpenCode](https://opencode.ai), put this in `opencode.json` in your project
  273. folder (or in `~/.config/opencode/opencode.json`):
  274. ```json
  275. {
  276. "$schema": "https://opencode.ai/config.json",
  277. "mcp": {
  278. "codesys": {
  279. "type": "local",
  280. "command": [
  281. "codesys-mcp-tool",
  282. "--codesys-path", "C:\\Program Files\\CODESYS 3.5.22.40\\CODESYS\\Common\\CODESYS.exe",
  283. "--codesys-profile", "CODESYS V3.5 SP22 Patch 4",
  284. "--workspace", "C:\\PLC\\Projects"
  285. ],
  286. "enabled": true
  287. }
  288. }
  289. }
  290. ```
  291. `opencode mcp list` should then show `codesys` as connected. Clients that read
  292. an `mcpServers` file (Cursor, Cline, VS Code and others) take the same
  293. `command` and `args` as the Claude Desktop example above.
  294. Tested on 13 November 2026 with OpenCode 1.19.5 and CODESYS V3.5 SP22: each of
  295. these models created a project, read and changed `PLC_PRG`, compiled, listed
  296. libraries and devices, and ran the simulation, without help.
  297. | Model | Result |
  298. | --- | --- |
  299. | DeepSeek V4.1 Flash | All steps passed |
  300. | Qwen 3.6 Plus | All steps passed |
  301. | GLM 5.3 | All steps passed |
  302. | MiniMax M3 | All steps passed |
  303. ![OpenCode with DeepSeek V4.1 Flash: a pump function block written, compiled and tested in CODESYS's simulation](docs/images/opencode-session.png)
  304. The live panel needs a client that shows MCP Apps cards (see
  305. [Live panel](#live-panel)). In other clients `open_sim_panel` does nothing
  306. visible; ask the model to open the workspace (`open_workspace`) to get the same
  307. view in your browser, or start the server with
  308. [`--show-window`](#watch-it-in-the-codesys-window) to watch the CODESYS window
  309. itself.
  310. ![The workspace in the browser after the OpenCode session: PLC_PRG's changes, and the review list with Accept and Revert for each object](docs/images/workspace-review.png)
  311. ## Safety
  312. - **No real controller.** The toolkit doesn't log in or download to a
  313. controller. It goes online only to CODESYS's own simulation, and every online
  314. call first checks that simulation mode is on.
  315. - **One approval covers every action.** That includes the actions that change
  316. or delete project code, so work on a copy of any project you can't afford to
  317. lose, or keep it in version control.
  318. - **Changes can be undone.** A checkpoint is taken when a project is opened, and
  319. `revert_object` puts an object back to it, including its methods and
  320. properties.
  321. - **Saved as it goes.** The project is saved after every change by default. Use
  322. `--no-autosave` to save only on request.
  323. - **The simulation can't change your project.** Editing is refused while it
  324. runs, and the simulation setting on the device is never saved.
  325. ## Configuration
  326. | Option | Meaning |
  327. | --- | --- |
  328. | `--codesys-path <exe>` | `CODESYS.exe` to run |
  329. | `--codesys-profile <name>` | Profile, e.g. `"CODESYS V3.5 SP21"` (file name in `CODESYS\Profiles`, without `.profile.xml`). A name that isn't installed is refused at start, with the installed ones listed |
  330. | `--codesys-additional-folder <dir>` | CODESYS's add-on folder, passed as `--additionalfolder`. SP22 installs add-ons such as Scripting there; the toolkit finds `CODESYS\AdditionalFolders\Default` by itself |
  331. | `--workspace <dir>` | Base folder for relative project paths (default: the working directory). Created if missing |
  332. | `--project <file>` | Open this project as soon as CODESYS is up |
  333. | `--session-dir <dir>` | Where session folders go (default: `%TEMP%\codesys-mcp-toolkit`) |
  334. | `--no-autostart` | Start CODESYS on the first tool call instead of at launch |
  335. | `--no-autosave` | Don't save after every change; use `save_project` |
  336. | `--viewer-port <port>` | Port of the browser workspace on 127.0.0.1 (default 5180, or the next free one) |
  337. | `--no-viewer` | Don't serve the browser workspace |
  338. | `--no-shared` | Run CODESYS in this process instead of the shared session |
  339. | `--attach <dir>` | Experimental: work in a CODESYS / Machine Expert window you already have open, instead of starting one. See [Working in an open window](#work-in-a-window-you-already-have-open-experimental) |
  340. | `--show-window` | Start CODESYS with its window instead of headless. See [Watch it in the CODESYS window](#watch-it-in-the-codesys-window) |
  341. ### Watch it in the CODESYS window
  342. By default CODESYS runs headless. With `--show-window` the server starts it with
  343. its normal window, so you can watch the work in any MCP client: every object the
  344. model creates or writes opens in its editor tab, with the new code in it.
  345. ![CODESYS started with --show-window: the model just created FB_Blink, and it opened in its editor](docs/images/codesys-window.png)
  346. While the simulation runs, the open editors show live values, as in CODESYS's own
  347. online mode:
  348. ![The same window during the simulation: PLC_PRG shows xEnable and xOn as TRUE](docs/images/codesys-window-sim.png)
  349. CODESYS's scripting API has no call for opening an editor, so the toolkit uses
  350. CODESYS's own (undocumented) frame for it, checked on SP21 and SP22. If a CODESYS
  351. version doesn't have it, nothing opens and everything else works as before.
  352. While the server is connected, the window is for watching: the toolkit's script
  353. keeps running in it (that is what lets it answer CODESYS's prompts, such as a
  354. storage-format upgrade, the same way as headless), so CODESYS treats it as one
  355. long operation. The status bar says "Executing script"; its **Click here to
  356. CANCEL** link stops the toolkit's script, so leave it alone while you work with
  357. the model. When the server stops, the script ends and the window is yours to
  358. work in.
  359. The toolkit never closes the window: not when a call hangs or a dialog waits
  360. for an answer (answer it in the window), and not when the server stops. Close it
  361. yourself when you're done; the next call then starts a new one.
  362. ### Several CODESYS versions
  363. To keep SP21 and SP22 side by side, add one server entry per version, each with
  364. its own `--codesys-path` and `--codesys-profile`.
  365. The toolkit never updates a project's compiler or library versions, and
  366. `open_project` says when they differ from the running CODESYS. A project that
  367. needs a newer compiler opens, but can't compile until you open it in that
  368. version. Each version keeps its own devices and libraries, so a project from an
  369. older CODESYS may report missing libraries until you update it in the CODESYS
  370. window.
  371. ### Shared session
  372. Claude Desktop may start the server more than once. All processes started with
  373. the same options share one background session, so only one CODESYS runs and the
  374. panel shows the project Claude is working on. The session stops two minutes
  375. after the last client disconnects. Its log is `daemon-<id>.log` in
  376. `%LOCALAPPDATA%\codesys-mcp-toolkit`.
  377. ### Work in a window you already have open (experimental)
  378. `--attach <dir>` makes the server use a CODESYS / Machine Expert window you
  379. already work in, instead of starting a hidden one. It starts nothing and kills
  380. nothing.
  381. 1. Add `--attach "C:\\PLC\\attach"` to the server arguments and start the
  382. server. It writes `C:\PLC\attach\scripts\start_attach.py`.
  383. 2. In your window, open the project, then run that file with **Tools >
  384. Scripting > Execute Script File**. It returns at once; a UI timer polls for
  385. requests, so the window stays usable.
  386. 3. Use the `codesys` tool as usual. `open_project` on the project that is
  387. already open just reuses it.
  388. 4. To stop, create an empty file `stop.flag` in the attach folder (or close the
  389. window).
  390. The window is busy only while a request runs, for example during `compile`.
  391. Your own unsaved edits are saved with the next change Claude makes
  392. (autosave), so use `--no-autosave` if that is not what you want. If the window
  393. stops answering (a dialog is open), the call fails with an error and nothing is
  394. closed; run `start_attach.py` again if the watcher was stopped.
  395. ## How it works
  396. ```
  397. MCP client ── stdio ──▶ codesys-mcp-tool (Node.js)
  398. │ requests/<id>.json ▶ operation name + JSON arguments
  399. │ ◀ results/<id>.json
  400. │ ◀ heartbeat.json idle or busy, with a deadline
  401. ▼
  402. CODESYS.exe --noUI --runscript=watcher.py
  403. └─ fixed operation handlers (IronPython 2.7)
  404. ```
  405. With `--show-window`, CODESYS starts without `--noUI` and runs the same watcher.
  406. - **No generated code.** Requests are an operation name plus JSON arguments,
  407. handled by fixed functions in `watcher/mcp_ops.py`.
  408. - **Hang detection.** The watcher reports `busy` with a deadline. If CODESYS
  409. blocks past it, the server kills it and starts a fresh one on the next call.
  410. - **No orphans.** The watcher exits when the server process goes away.
  411. - **Modal dialogs** are suppressed and logged, so they can't freeze CODESYS.
  412. - **UTF-8** from end to end.
  413. - **Localised names.** Object kinds come from CODESYS type GUIDs, not names, so
  414. a German task folder called `Taskkonfiguration` works.
  415. ## Troubleshooting
  416. | Message | What to do |
  417. | --- | --- |
  418. | **CODESYS is still starting** | The first start after boot can take minutes. Check `codesys_status`, then try again. |
  419. | **`startup_failed`** or **`startup_timeout`** | Check the profile name and that CODESYS starts by hand. The error includes the last lines of `watcher.log`. |
  420. | **Library errors after `create_project`** ([#4](https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues/4)) | The default template is brought up to the running CODESYS, so its libraries should resolve. A template you pass yourself is used as it is. If libraries are still missing, install them with the CODESYS Library Repository. |
  421. | **`hung`** or **`timeout`** | CODESYS was restarted. Re-open the project. With `--show-window` nothing is closed: check the window. |
  422. | **`dialog`** | CODESYS opened a dialog, named in the error, that a session without a window can't answer. CODESYS was stopped and restarts on the next call. Do the same step once in the CODESYS window, answer the dialog there, and try again. With `--show-window`, answer it in the window. |
  423. Each session folder keeps a `watcher.log`.
  424. ## Development
  425. ```bash
  426. npm install
  427. npm test # unit, bridge and tool tests (no CODESYS needed)
  428. CODESYS_LIVE=1 npx vitest run test/live # end-to-end against your CODESYS
  429. npm run build # server and the single-file panel
  430. ```
  431. The normal tests run the real watcher under CPython 3 against a fake
  432. `scriptengine` (`test/fake/`). Watcher code must stay valid IronPython 2.7:
  433. ASCII-only, no f-strings.
  434. To work on the panel without Claude Desktop, run the dev host, then open
  435. http://localhost:5199:
  436. ```bash
  437. npm run build:panel && node scripts/dev-host/run.mjs 5199
  438. ```
  439. See [CONTRIBUTING.md](CONTRIBUTING.md) to get involved.
  440. ## Migrating from v1
  441. - Everything is now an action of the one `codesys` tool.
  442. - Actions don't take `projectFilePath`. Call `open_project` once.
  443. - `create_pou`, `create_method` and `create_property` are now `create_object`
  444. with a `kind`.
  445. - `set_pou_code` is now `write_object`.
  446. - `compile_project` is now `compile`, and it returns the errors.
  447. - Read access is through actions (`read_objects`, `get_project_tree`) instead of
  448. resources, so it works in Claude Desktop
  449. ([#6](https://github.com/johannesPettersson80/codesys-mcp-toolkit/issues/6)).
  450. ## Acknowledgements
  451. The persistent-watcher design borrows ideas from
  452. [zbest1000/mcptoolkit-for-codesys](https://github.com/zbest1000/mcptoolkit-for-codesys)
  453. (op-handler registry, heartbeat, prompt handling) and
  454. [phobicdotno/Codesys-MCP-Master](https://github.com/phobicdotno/Codesys-MCP-Master)
  455. (file-queue IPC, version-safe opening). Both are MIT-licensed.
  456. The [Chinese README](README.zh-CN.md) was reviewed by Zhen Yang (Alfabete-spec).
  457. ## License
  458. [MIT](LICENSE)
  459. CODESYS is a trademark of CODESYS GmbH. This project is independent and isn't
  460. affiliated with or endorsed by CODESYS GmbH.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.