Skip to main content
Glama
ctrlX Engineering MCP

ctrlX Engineering MCP

by rduffy190

ctrlX Engineering MCP

An MCP server that lets Claude Code drive ctrlX PLC Engineering (CODESYS V3) through the CODESYS Scripting Engine: read and write POUs, build, go online, start/stop, read and write variables, and record traces.

Claude Code --stdio--> server/server.py (CPython, FastMCP)
                          | JSON lines over TCP + token (SSH reverse tunnel)
                          v
   PLC Engineering (Windows) running bridge/bridge.py (IronPython 2.7, inside the IDE)

Tested with ctrlX PLC Engineering 4.6.2 on Linux+Windows split setup (against a ctrlX CORE), and 4.6.1 (ScriptEngine 4.2.0.0) with everything on one Windows PC.

Setup

Everything on one Windows PC (Claude Code and PLC Engineering together)

scripts\install_windows.bat

It creates .venv, installs the requirements, creates scripts\.ctrlx_token, writes scripts\config.bat with TUNNEL=0, and registers the server with claude mcp add (local scope, so it overrides the Linux-style .mcp.json in this folder). The server reads the token from the file when CTRLX_MCP_TOKEN is not set. Then run scripts\start_bridge.bat, start Claude Code in this folder and ask it to ping. No SSH or tunnel is involved: the server talks to the bridge on 127.0.0.1:8765 directly. The ladder tools need the skills in %USERPROFILE%\.claude\skills (or CTRLX_SKILLS_DIR).

Split setup (Claude Code on Linux/WSL, PLC Engineering on Windows)

Linux / WSL (where Claude Code runs)

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
scripts/install_token.sh          # creates .ctrlx_token, exports CTRLX_MCP_TOKEN from ~/.bashrc

.mcp.json registers the server for Claude Code in this folder. The token is read from the environment, so open a new terminal after installing it.

Windows (where PLC Engineering runs)

  1. Copy this folder (at least bridge/ and scripts/) to the Windows machine.

  2. Copy the token printed by install_token.sh into scripts\.ctrlx_token.

  3. Copy scripts\config.example.bat to scripts\config.bat and edit it (Linux user and host, IDE path, optional project to open).

  4. Make SSH login to the Linux box key-based (ssh-keygen, then ssh-copy-id), or the tunnel window waits for a password.

  5. Run scripts\start_bridge.bat. It opens the tunnel and starts the IDE with the bridge loaded.

The bridge listens on 127.0.0.1 only, and every request needs the token. CTRLX_MCP_PORT changes the port (default 8765), CTRLX_MCP_ALLOW_EXEC=0 disables the exec_script tool.

Check it from Linux: ask Claude to ping, or run

CTRLX_MCP_TOKEN=$(cat .ctrlx_token) .venv/bin/python -c "import sys; sys.path.insert(0,'server'); import server; print(server.call('ping'))"

If the IDE misbehaves when the script loads at startup, set AUTORUN=0 in config.bat and run the bridge from Tools > Scripting > Execute Script File. Its log is %TEMP%\ctrlx_bridge.log (online context saved and ui dispatch ready should appear, then loop started).

Related MCP server: TIA-Portal MCP-Server

Windows vs Linux

Which setup you have decides how the server is registered and what it can do for you. The tools are the same in both; the differences are in starting the IDE and where files live.

Everything on one Windows PC

Claude Code on Linux/WSL, IDE on Windows (tunnel)

Register the server

scripts\install_windows.bat (or add it at user scope in ~/.claude.json so every workspace sees it)

.mcp.json in this folder (.venv/bin/python); open a new terminal after install_token.sh

Token

scripts\.ctrlx_token, read by the server

CTRLX_MCP_TOKEN in the environment, the same value in scripts\.ctrlx_token on Windows

Reaching the bridge

direct, 127.0.0.1:8765 (TUNNEL=0)

SSH reverse tunnel opened by start_bridge.bat (TUNNEL=1, needs key-based SSH to the Linux box)

Starting the IDE

automatic: the first tool call runs start_bridge.bat and waits about a minute (CTRLX_AUTOSTART=0 turns it off)

by hand: run scripts\start_bridge.bat on the Windows machine before using the tools

Skills (ctrlx-engineer, codesys-lad, ctrlx-hmi)

%USERPROFILE%\.claude\skills or CTRLX_SKILLS_DIR

~/.claude/skills or CTRLX_SKILLS_DIR on the Linux side

Paths you pass

Windows paths, for the IDE and the server alike

Project and object paths are Windows paths on the IDE machine (open_project, import_plcopen with file); files for the server (import_visu's export, build_hmi's screen) are Linux paths and are sent over the tunnel as text

HMI import

the bridge runs the headless helper IDE on this PC

the same: the bridge, on the Windows machine, runs it; nothing extra to install on Linux

Not available over the tunnel: auto-start (the server cannot launch an IDE on another machine). The helper IDE for import_visu needs a free port on the Windows machine (CTRLX_HELPER_PORT, default 8766), which is not part of the tunnel.

Tools

Project: ping, open_project, save_project, get_tree, get_pou, set_pou, create_pou, add_task_call, remove_task_call, list_io, map_io, create_dut, create_gvl, create_folder, move_object, delete_object, build, messages. create_folder (a path such as 02_Gapper/POUs creates every missing level, repeats are safe) and move_object group objects into folders; names do not change, so code and task calls keep working. The application must be logged out. HMI: build_hmi (screen definition to .export, plus SVG previews), import_visu (a visugen .export into the open project), add_web_visu (web visualization that starts on a visu), publish_hmi (build, import, web visu and save in one call; needs the ctrlx-hmi skill).

PLCopenXML: export_plcopen, import_plcopen. Ladder: ladder_check, ladder_import, ladder_export. Online (the user logs in and downloads in the IDE themselves; login can fail on the download confirmation dialog): login, logout, run_state, plc_start, plc_stop, read_var, write_var. Trace: list_traces, get_trace, create_trace, trace_setup, trace_run, trace_status, trace_stop, trace_wait, trace_save. Escape hatch: exec_script (runs IronPython in the IDE; use dir() to explore the API).

Object paths are /-separated names from the project root, for example Device/Plc Logic/Application/PRG_Main. Name matching is exact; check get_tree for the spelling (Plc Logic vs PLC Logic).

Rules for Claude

  • Always ask the user how to download the application before login. An application download can replace the program, reset variables to their initial values and stop a running application. (A trace download is a different thing, see Tracing.) Do not decide it, and do not log in "just to look" at a running machine.

  • change="Never" stops a running controller when you log in (seen on a ctrlX CORE). The default is Try (online change), which keeps it running; it is also what trace_run uses.

  • To attach to a running PLC use login with change="Try". The download flag is passed to the IDE as "delete foreign applications" on the controller, needs extra rights (a permissions error otherwise) and defaults to False; leave it off unless the user asks.

  • Always ask the user how many samples the trace should use before trace_setup; samples is required and is not defaulted.

  • write_var, plc_start, plc_stop and login affect a running machine; confirm first.

  • A program only runs if a task calls it. After importing or creating a PRG_, use add_task_call (default task MainTask). The IDE may show a dialog while the task is re-imported; tell the user to watch it.

Tracing

create_trace name="MyTrace" adds an empty trace object (scripts cannot: trace.create returns a stub, so the bridge imports a blank trace from server/templates/trace.template.native). Adding one in the IDE (right-click the Application > Add Object > Trace) works too. list_traces and get_trace read what exists; trace_setup changes only the arguments you give (variables, add_variables, remove_variables, trigger, trigger_enabled, auto_start, task_name, record_condition, comment). Then:

trace_setup  trace="Device/Plc Logic/Application/MyTrace"  samples=<ask the user>  variables=["PRG_Main.bEnable", ...]
trace_run    app="Device/Plc Logic/Application"  trace=...     # downloads and starts
... do things (write_var, plc_start, ...) ...
trace_save   trace=...      # stops if needed, exports, returns the value changes per variable

Repeat runs of the same trace: trace_run ... download=False re-arms the trigger and starts the trace already on the controller, with no download. trace_stop stops it early. Download again whenever the trace's variables or settings change.

The trace download is not an application download. It sends only the trace configuration to the controller; the PLC program is untouched and the controller keeps running. On trace download the IDE shows a dialog that the user may have to acknowledge. trace_run waits for it, so tell the user to watch the IDE.

trace_save takes mode (changes, samples for every sample, csv for the raw export), a start_ms/end_ms window, a variables filter and upload=True to pull the data from the controller first; trace_status shows whether it is running or has been downloaded. A trace level is a number; leave it out for a BOOL trigger.

trace_setup also puts the variables in the trace's first diagram; without that they are recorded but not drawn. Variable names are relative to the application: no Application. prefix. With the prefix the download silently does nothing. A trace stops itself once its buffer has filled; trace_save copes with that. It returns a table of the points where any value changed (time_ms plus one column per variable); sampling follows the task cycle.

Ladder and other graphical code (PLCopenXML)

get_pou and set_pou handle text only: the declaration of any POU, and the body of an ST POU. create_pou can make an ld/fbd POU, but its body cannot be set from text (set_pou says so). Graphical code goes in as PLCopenXML:

The ladder tools use two Claude Code skills on the Linux side, installed side by side in ~/.claude/skills (or set CTRLX_SKILLS_DIR): ctrlx-engineer (st_to_plcopenxml.py, the converter) and codesys-lad (the ladder compiler and ld_trace.py). Claude passes the source text to the tool; the server runs the skill's scripts on it. Nothing is copied to the Windows PC.

  1. ladder_check sources={"FB_X.st": "<text>"} compiles without touching the IDE and returns the converter's warnings plus trace: every output as a boolean expression, per network. Check it against the intent. sources maps a .st file name to its text (a GVL is named after its file); libs holds declarations of library POUs the rungs call. A source error raises, with the network and the position.

  2. Ask the user, then logout (the IDE refuses to add objects while logged in; the controller keeps running), and export_plcopen the objects you are about to replace as a backup.

  3. ladder_import with the same arguments compiles and imports in one step; nothing is imported if the source does not compile. The XML goes through the tunnel as text and the bridge imports it from a temp file on the Windows side, so no shared folder is needed. conflict is Replace, Copy or Skip for objects that already exist; confirm Replace with the user.

  4. build, fix errors, login as the user directs.

To review ladder that is already in the project, ladder_export paths=[...] returns the same trace for it. include_xml=True adds the raw PLCopenXML. import_plcopen and export_plcopen move raw XML for anything you built another way.

How the bridge works (and why)

These were found by trial; they explain the odd structure of bridge/bridge.py.

  • UI thread. --runscript runs the script on the IDE's UI thread, and a script that never returns freezes the IDE (a message pump in the loop did not help). So the script returns at once; a background thread accepts connections and runs each request on the UI thread through a hidden WinForms control (Control.Invoke). Building or logging in from the background thread fails with An item with the same key has already been added (compiler).

  • Stack empty. The online module keeps a stack of running scripts and raises Stack empty when it is empty, which it is once the bridge script has returned. The bridge saves the stack entry at startup and pushes it back before online calls.

  • CTRLX_MCP_BLOCK=1 serves on the script thread and never returns. Use it only for headless --noUI runs; the IDE window is frozen while it runs.

  • Long calls (download, build) block the IDE UI while they run.

  • Stale online object. The bridge caches one online object per application. After a login or logout in the IDE it can go stale: reads fail with Invalid variable reference and writes do nothing. read_var and write_var retry once with a fresh object.

  • Imports go where they are called. import_xml on the project puts new objects at the project root; on the application it puts them in the application. import_plcopen calls it on parent (default the application). Objects that already exist are matched and replaced either way.

  • build is application.build(), not a project method. Build messages come from system.get_message_categories(True); do not call system.clear_messages() (it left the Messages pane broken). Compile problems can also surface only at login.

  • Do not force-kill the IDE after a hung call; close it normally.

  • I/O mapping. list_io shows a card's channels (an input card has Input channels, an output card Output); map_io maps, remaps or unmaps them (variable null unmaps). The mapping string needs the application name in front, Application.GVL_IO.bDI_Start; map_io adds it. Without it the build reports "Invalid application in mapping". Cards live under Device/Realtime_Data/<master>/<card>. A mapping change reaches the controller on the next download.

  • Task calls. The scripting engine has no call to add a program to a task. add_task_call exports the task (export_native), adds an entry to its PouList and re-imports it; the IDE asks the user to allow the task import. remove_task_call removes the child call object directly (no dialog).

  • Non-ASCII text. IronPython's json encoder fails on a non-ASCII str (it tries to UTF-8-decode text that is already decoded), which lost the reply and timed out the client. _jsonable hands it UTF-8 bytes.

Example

examples/intersection/ is a four-way intersection in ladder (fixed-time NS/EW cycle, fault input with flashing red, reset), written to test the ladder tools. Build and simulate it with the ladder skills (st_to_plcopenxml.py, then test_intersection.py), import it with ladder_import, then add_task_call for PRG_Intersection so a task runs it.

Tests

.venv/bin/python tests/test_protocol.py     # bridge protocol, stubbed scriptengine
.venv/bin/python tests/test_mcp_e2e.py      # MCP server against a stubbed bridge

These do not run against a real IDE. What has been run for real: ping, tree, POU read/write, save_project, build, login with download, logout, run_state, plc_start, read_var, write_var, and the trace flow above, and PLCopenXML export/import (export_xml, and import_xml with text written to a temp file) including a ladder block, driven through exec_script. Not exercised yet: the export_plcopen, import_plcopen and ladder_* tools end to end, create_pou/create_dut/create_gvl/delete_object, create_folder/move_object against the stubs only (the same scripting calls, create_folder and move, were run for real through exec_script), plc_stop, trigger-based traces, and starting the bridge with --runscript at IDE startup (AUTORUN=1; the menu route is what has been tested).

License

MIT, see LICENSE.

HMI import

A visualization export from the ctrlx-hmi skill carries the whole device tree, and an open project refuses it ("cannot be pasted here"). The server sends the export to the bridge as text (visu_import), so it works the same from Linux over the tunnel. The bridge, on the machine with the IDE, starts a second, headless IDE (--noUI, its windows hidden) as a helper on CTRLX_HELPER_PORT (default 8766), imports the export into a temp project there, exports only the Visualization Manager, text lists and visus as object files (visu_extract), stops the helper and imports the files into the open project (visu_apply). Same-named objects are replaced; an existing Visualization Manager is kept. add_web_visu fills server/templates/webvisu.template.native (a real export of a WebVisualization) with the start visu and client size (1920x1080 by default). The scripting engine has no call to create visualizations. The helper's log is %TEMP%\ctrlx_bridge_<port>.log; start_bridge.bat also takes BRIDGE_PORT, BRIDGE_PROJECT and BRIDGE_HEADLESS=1 for a second instance by hand. build_hmi and publish_hmi run the skill's generator on the machine running the server, which needs the ctrlx-hmi skill there (CTRLX_SKILLS_DIR).

Auto-start

On Windows, when the bridge is on this PC and a tool call finds nothing listening, the server runs scripts\start_bridge.bat itself (IDE plus bridge, and the project from config.bat) and waits up to three minutes for it, so the first call after boot takes about a minute. It tries once per five minutes. CTRLX_AUTOSTART=0 turns it off.

Over the SSH tunnel (Linux client) the server cannot start the IDE, so start scripts\start_bridge.bat on the Windows machine first; everything else, including the HMI tools, works the same.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables interaction with Siemens TIA Portal projects directly from VS Code or Claude Desktop using GitHub Copilot and the TIA Openness API. It supports connecting to TIA Portal instances, exporting blocks or types, and performing project operations like compilation via natural language.
      64
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with B\&R Automation Studio projects by building code, running ARsim simulators, and reading or writing OPC UA variables. It facilitates industrial automation development and real-time variable integration through natural language commands.
      17
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to connect to Allen-Bradley, Siemens, and CODESYS PLC projects for discovering, asking questions about, analyzing, and proposing code changes, with access to live tag values and version exports under permission-scoped controls.
      -