Site icon Efficient Coder

CODESYS AI Automation: Complete Guide to Setup codesys-mcp-persistent for Claude

高效码农

How to Control CODESYS with AI: A Complete Setup Guide for codesys-mcp-persistent

“

If you’ve spent time as a PLC engineer, you already know the drill: copy-pasting Function Blocks that are almost identical, manually wiring up device parameters, hunting down cryptic compiler errors one by one. None of that is engineering — it’s busywork. With MCP (Model Context Protocol), Claude can operate CODESYS directly on your behalf, handling those repetitive tasks while you focus on the logic that actually matters. No AI development background required.

Table of Contents

  1. What Is CODESYS MCP?
  2. Which CODESYS MCP Options Exist?
  3. Why Choose codesys-mcp-persistent?
  4. Prerequisites
  5. Installation (No Python Needed)
  6. Registering the MCP Server in Claude Code
  7. What Can the 28 Tools Actually Do?
  8. Persistent Mode vs. Headless Mode
  9. Frequently Asked Questions
  10. Summary and Recommendations

What Is CODESYS MCP?

CODESYS is one of the most widely adopted PLC development platforms in industrial automation worldwide. Built on the IEC 61131-3 standard, it supports multiple programming languages — Structured Text (ST), Ladder Diagram (LD), Function Block Diagram (FBD), and more.

What most engineers don’t know is that CODESYS has a built-in Scripting Engine: an interface that lets external programs drive the IDE through Python scripts to perform operations like creating POUs, compiling projects, or connecting to PLC devices.

MCP — Model Context Protocol — is an open protocol developed by Anthropic. It gives AI assistants a standardized way to call external tools. Put those two things together and you get CODESYS MCP: a bridge that lets Claude operate your PLC development environment the same way a human engineer would.

Here’s how the full chain looks:

You  →  describe your intent in plain English
          ↓
     Claude Code  →  understands the task
          ↓
  CODESYS MCP Server  →  translates into CODESYS operations
          ↓
     CODESYS IDE  →  executes, updates in real time
          ↓
     PLC / SoftPLC runtime

Which CODESYS MCP Options Exist?

There are currently three main CODESYS MCP implementations in the community. They differ in technical approach, feature depth, and setup complexity:

Option Language Tools Online PLC ops Setup difficulty
codesys-mcp (VS Code bridge) TypeScript Limited ❌ Requires VS Code
codesys-mcp-persistent TypeScript / Node.js 28 ✅ Lowest
Official CODESYS GmbH MCP Native integration Broad ✅ Requires SP22

The VS Code bridge option works well if you already develop in VS Code, but its toolset is limited and it does not support live PLC interaction.

The official CODESYS GmbH option is the most stable — but it requires upgrading to V3.5 SP22, which many production environments simply can’t do on short notice.

codesys-mcp-persistent is the most feature-complete community option available right now: pure Node.js, no Python dependency, 28 tools, and full support for online PLC variable reads and writes.

Why Choose codesys-mcp-persistent?

No Python Environment Required

Many automation engineers don’t have Python installed, and setting it up just for a toolchain dependency is friction you don’t need. This project is built entirely on Node.js. If you have Node.js already (which is likely), one command installs everything.

The CODESYS UI Stays Open

This is the defining feature of persistent mode. Other solutions spawn a new CODESYS process per command, run the script invisibly, and shut it down. You never see what happened.

Persistent mode works differently: the CODESYS interface stays open the entire time. Every action Claude takes — adding a POU, editing code, triggering a build — appears in real time on your screen. You can step in at any point, or simply watch as the work gets done alongside you.

28 Tools Cover the Entire Development Cycle

From creating a new project all the way to downloading compiled code to a PLC and reading live variable values, the toolset covers the complete workflow without requiring you to switch between multiple systems.

Drop-in Replacement for @codesys/mcp-toolkit

Already using @codesys/mcp-toolkit? This project is a direct replacement. Tool names and parameters are fully compatible — your existing prompts and automation scripts work without modification.

Prerequisites

Before getting started, confirm these are in place:

  • Operating system: Windows (CODESYS is Windows-only)
  • CODESYS version: V3.5 SP19 or SP21, installed with the Scripting Engine component enabled
  • Node.js: version 18.0.0 or higher — run node --version in a terminal to check
  • Claude Code CLI: installed and authenticated

If Node.js isn’t installed, download the LTS release from nodejs.org and use the default installer options.

“

Important: The Scripting Engine component is the foundation that all CODESYS MCP solutions depend on. If it wasn’t selected during your original installation, you’ll need to re-run the CODESYS installer and add it via the repair/modify option.

Installation (No Python Needed)

Step 1 — Install codesys-mcp-persistent globally

Open PowerShell or Command Prompt and run:

npm install -g codesys-mcp-persistent

Once it finishes, verify the installation:

codesys-mcp-persistent --version

If a version number appears, you’re good to move on.

Step 2 — Detect your CODESYS installation details

Run the built-in detection command:

codesys-mcp-persistent --detect

This scans both Program Files and Program Files (x86) for CODESYS installations and prints something like:

Found CODESYS installations:
  - C:\Program Files\CODESYS 3.5.21.0\CODESYS\Common\CODESYS.exe
    Profile: CODESYS V3.5 SP21 Patch 3

Copy both the path and the profile name exactly. You’ll need them in the next step.

“

⚠️ The profile name must match character-for-character, including capitalization and spaces. To double-check the exact name, open CODESYS and go to Tools → Options → Environment → Profiles.

Step 3 — Test the tool in isolation before connecting to Claude Code

Before wiring this into Claude Code, confirm it can launch CODESYS on its own:

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

If the CODESYS UI opens and the terminal reports ready, the paths are correct and you’re ready for the final step.

Registering the MCP Server in Claude Code

Option A — CLI registration (recommended)

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"
  ]
}'

“

Note: Inside a JSON string, backslashes must be doubled — \\ instead of \.

Option B — Edit .mcp.json directly

Find or create a .mcp.json file in your project root or home directory, then add:

{
  "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"
      ]
    }
  }
}

Verify the registration

claude mcp list

When codesys shows a connected status, the setup is complete.

What Can the 28 Tools Actually Do?

This is where codesys-mcp-persistent separates itself from the alternatives. Tools are grouped into five categories:

Instance Management (3 tools)

Tool What it does
launch_codesys Manually start CODESYS (used with --no-auto-launch)
shutdown_codesys Shut down the persistent CODESYS instance
get_codesys_status Query current state, process ID, and execution mode

Project Tools (5 tools)

Tool What it does
open_project Open an existing .project file
create_project Create a new project from the standard template
save_project Save the currently open project
compile_project Build the primary application with structured error output (120s timeout)
get_compile_messages Retrieve the last compiler output without triggering a new build

POU and Code Authoring (11 tools)

Tool What it does
create_pou Create a Program, Function Block, or Function
set_pou_code Set declaration and/or implementation code
create_property Add a property inside a Function Block
create_method Add a method inside a Function Block
create_dut Create a Data Unit Type (Structure, Enumeration, Union, or Alias)
create_gvl Create a Global Variable List with optional initial declarations
create_folder Add an organizational folder to the project tree
delete_object Delete any project object (POU, DUT, GVL, folder, etc.)
rename_object Rename any project object
get_all_pou_code Bulk-read all declaration and implementation code in the project (120s timeout)

Online and Runtime Tools (7 tools)

This category has no equivalent in the other community options. It enables live PLC interaction directly through Claude:

Tool What it does
connect_to_device Log in to the PLC runtime (requires a configured device/gateway in the project)
disconnect_from_device Log out from the PLC runtime
get_application_state Check whether the PLC application is running, stopped, or in an exception state
read_variable Read a live variable value from the running PLC, e.g. PLC_PRG.bMotorRunning
write_variable Write or force a variable value on the running PLC
download_to_device Download the compiled application to the PLC — attempts an online change first (120s timeout)
start_stop_application Start or stop the PLC application

Library Management (2 tools)

Tool What it does
list_project_libraries List all libraries referenced in the project with version details
add_library Add a library reference to the project

Persistent Mode vs. Headless Mode

Persistent Mode (default — recommended for most users)

This is the feature that makes codesys-mcp-persistent worth using. Here’s exactly what happens under the hood:

  1. The server launches CODESYS.exe with --runscript=watcher.py — without the --noUI flag, so the IDE opens normally
  2. The watcher script starts a .NET background thread that polls a commands/ directory, then immediately returns control to CODESYS so the UI stays fully responsive
  3. When Claude calls a tool, the server writes a Python script and a .command.json file into commands/
  4. The background thread picks up the command and marshals execution onto the CODESYS UI thread via system.execute_on_primary_thread()
  5. Results are written atomically to results/ and returned to Claude
  6. Every change the AI makes shows up live in your IDE

During synchronous operations like project compilation or opening a file, the UI may briefly pause — this is expected behavior and resolves automatically once the operation completes.

Headless Mode (fallback for server or CI use)

In headless mode, each tool call spawns a new CODESYS process with the --noUI flag, runs the script, and exits. There’s no visible interface. This is appropriate for:

  • Automated build pipelines or CI/CD environments
  • Server-side deployments where a display isn’t available
  • Situations where persistent mode fails to start (with --fallback-headless enabled)

Practical Usage Examples

Once the setup is complete, you interact with CODESYS entirely through plain English in Claude Code. For example:

Create a motor control Function Block called FB_MotorControl with:
- Inputs: bStart (BOOL), bStop (BOOL), rSpeedSetpoint (REAL)
- Outputs: bRunning (BOOL), bFault (BOOL)
- Basic start/stop logic with fault detection

Claude will call create_pou and set_pou_code to build and populate the Function Block directly in the open CODESYS IDE, then call compile_project to verify there are no syntax errors — all visible in real time.

Or for a live PLC task:

Read the current value of PLC_PRG.rActualSpeed.
If it's above 1500, write TRUE to PLC_PRG.bOverspeed.

Claude calls read_variable, evaluates the result, and conditionally calls write_variable — no manual CODESYS interaction needed.

CLI Reference

Flag Description Default
-p, --codesys-path Path to the CODESYS executable CODESYS_PATH env var or auto-detected
-f, --codesys-profile CODESYS profile name CODESYS_PROFILE env var or CODESYS V3.5 SP21
-w, --workspace Working directory for relative paths Current directory
-m, --mode persistent (with UI) or headless (no UI) persistent
--no-auto-launch Don’t launch CODESYS on startup Auto-launch enabled
--fallback-headless Fall back to headless if persistent fails true
--keep-alive Keep CODESYS running after the server stops false
--timeout Default command timeout in milliseconds 60000
--detect List installed CODESYS versions and exit —
--verbose Enable verbose logging —
--debug Enable debug logging —

To avoid typing long paths on every run, set environment variables as persistent defaults:

$env:CODESYS_PATH = "C:\Program Files\CODESYS 3.5.21.0\CODESYS\Common\CODESYS.exe"
$env:CODESYS_PROFILE = "CODESYS V3.5 SP21 Patch 3"

Frequently Asked Questions

The codesys-mcp-persistent command is not recognized after installation. What should I do?

This usually means the npm global bin directory isn’t in your system PATH. Run the following to find where npm installs global packages, then add that directory to your PATH:

npm config get prefix
# Add the returned path + \bin to your PATH environment variable

The --detect command doesn’t find my CODESYS installation.

Navigate manually using File Explorer to locate CODESYS.exe. It’s typically at:

C:\Program Files\CODESYS 3.5.XX.X\CODESYS\Common\CODESYS.exe

Copy the full path and pass it directly to --codesys-path.

The watcher times out — no ready signal within 60 seconds. How do I debug this?

Work through these checks in order:

  1. Confirm the CODESYS executable path is correct
  2. Confirm the profile name matches exactly, including case and spaces
  3. Check whether CODESYS is opening a modal dialog on launch (such as a license prompt)
  4. Add --verbose to the command and review the detailed output

The online tools — connect_to_device, read_variable, etc. — are failing.

Online operations have three hard requirements:

  • A device and gateway must be configured inside the CODESYS project
  • The project must have been compiled successfully at least once
  • The PLC or SoftPLC runtime must be reachable from the current machine

Commands are timing out on large projects.

The default timeout is 60 seconds. Compile and download operations get 120 seconds. For large projects, increase the limit with --timeout:

codesys-mcp-persistent --timeout 300000 ...

Also check the CODESYS Messages window — a hidden modal dialog or background error is the most common cause of unexpected hangs.

The project file opens as locked.

Another CODESYS instance likely has the project open. Close that instance first, or switch to persistent mode which ensures only a single CODESYS process is running at a time.

Summary and Recommendations

codesys-mcp-persistent is the most complete community-built integration between CODESYS and AI assistants available today. It’s a practical fit if you:

  • Want to use Claude to accelerate PLC code writing and eliminate repetitive boilerplate
  • Need to bulk-generate project structures — multiple POUs, GVLs, DUTs — from a specification
  • Frequently read and write PLC variables during debugging or commissioning
  • Want to standardize your team’s project structure using AI-generated, convention-compliant templates

The entire setup takes three commands: install globally with npm install -g codesys-mcp-persistent, find your paths with --detect, and register the server with claude mcp add-json. No Python runtime, no extra middleware, no complex dependency chain.

The one thing to verify upfront: CODESYS must have been installed with the Scripting Engine component. This is the underlying interface that every CODESYS MCP solution depends on. If it’s missing, re-run the CODESYS installer and select the component via the repair/modify option.

This article is based on the documentation for the codesys-mcp-persistent open source project. Repository: github.com/luke-harriman/Codesys-MCP. License: MIT.

Exit mobile version