Free: a CODESYS MCP server — drive the IDE from an AI agent

We published a TIA Portal MCP server a while back and the same question kept coming back: what about CODESYS?

So here it is. An MCP server that exposes the CODESYS V3.5 scripting API as 41 tools, free to download.

The thing that makes it different from a headless wrapper: it keeps CODESYS open and visible. Most scripting bridges spawn a throwaway --noUI process per command, so you never see anything happen. This one launches the IDE normally and routes every tool call through a watcher running inside that same instance — blocks appear in the tree as they are created, code lands in the editor, and you can keep working in CODESYS alongside the agent.

What it lets an agent do

• Projects — open, create (from a template or the standard project), save, compile with structured error output
• Code authoring — create Programs, Function Blocks, Functions, methods, properties, DUTs and GVLs; write declarations and implementations; bulk-read every POU in the project; regex search, find references, and a two-phase symbol rename with a dry run by default
• Online — log in to the runtime, download the application (online change or full), start and stop, read live variables, force values, and sample a set of variables over time
• Device tree — browse the device repository, add devices, inspect node parameters, map fieldbus I/O channels to global variables
• Libraries — list and add library references
• Archiving — save the open project as a .projectarchive

In practice: “create an FB for the tank sequence, write the ST, compile it, and tell me what failed” — against the real project, with the IDE in front of you.

What you need first

• Windows
• Node.js 18+
• CODESYS V3.5 SP19 or SP20 for the persistent, UI-visible mode
• An MCP-capable client — Claude Code, Claude Desktop, VS Code, Cursor, or your own agent on an MCP SDK

Read this before you install on SP21. CODESYS removed the scripting call the persistent mode depends on somewhere in the SP21 line. On SP21+ the server launches and then every tool call fails. Run it with --mode headless instead, which spawns a --noUI process per call and works fine — you just lose the live IDE view. SP19 and SP20 are unaffected.

Install

Unzip it, then from the project root:

npm install
npm run build
npm link

Register it with your MCP client

The server is a standard stdio MCP server, so the config is a command and its args. For a JSON-config client (Claude Desktop, VS Code, Cursor and most others):

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

Not sure what you have installed? Run codesys-mcp-persistent --detect and it lists every CODESYS install it can find, with the paths to use above.

Things worth knowing

• set_pou_code saves to disk on every successful call. Ctrl+Z in the IDE will not bring the old content back — keep the project in version control.
• write_variable forces the value. It stays forced until you unforce it or restart the runtime. That is exactly what you want on a bench and exactly what you do not want on a live machine.
• add_library needs the fully-qualified placeholder as shown in the Library Manager (e.g. Standard, * (System)). Bare names will not resolve.
• Online tools need a real target — a configured device or gateway, a successful compile, and a reachable PLC (or simulation mode turned on).

The full tool list, the IPC design and a long troubleshooting section are in the README inside the zip.