Codesys-MCP/python_scripting/how-to-use-codesys-mcp.md

How To Use CODESYS MCP Bridge

This guide explains day-to-day usage of your CODESYS MCP bridge from Cursor.

1) Confirm prerequisites

• Windows VM agent is running on port 8787
• Linux host can reach VM IP
• Same token is configured on both sides:
  • VM: CODESYS_AGENT_TOKEN
  • Cursor MCP config: CODESYS_AGENT_TOKEN
• CODESYS IDE must be closed for write operations (read operations work even with IDE open)

Quick connectivity check from Linux:

curl http://10.77.30.50:8787/health

2) Cursor MCP config (working example)

Update ~/.cursor/mcp.json:

{
  "mcpServers": {
    "codesys-bridge": {
      "command": "/home/nearxos/Projects/.venvs/winrm/bin/python",
      "args": [
        "/home/nearxos/Projects/gitea/codesys-mcp-agent/python_scripting/mcp_codesys_bridge/server.py"
      ],
      "env": {
        "CODESYS_AGENT_URL": "http://10.77.30.50:8787",
        "CODESYS_AGENT_TOKEN": "<your-token>",
        "CODESYS_AGENT_REQUEST_TIMEOUT_SEC": "30"
      }
    }
  }
}

Reload MCP servers or restart Cursor after editing.

3) Available MCP tools

Reading (works even with IDE open)

Tool	Purpose
codesys_health	Check VM agent status
codesys_get_job	Poll job status/result by ID
read_project_inventory	Read project tree + textual sources (POUs, GVLs, NVLs, structs)
read_device_io	Read device tree, I/O channels, variable mappings

Writing (requires CODESYS IDE to be closed)

Tool	Purpose
write_pou	Update single or batch textual objects (declaration + implementation)
write_io_mapping	Map IEC variables to device I/O channels
manage_device	Add, remove, update, rename devices; set device parameters
sync_project	Batch push -- apply textual updates, IO mappings, and device params in one save

Build & Deploy

Tool	Purpose
create_project	Create new empty CODESYS project on VM
build_project	Compile a project
download_to_device	Deploy to PLC (requires CODESYS_AGENT_ALLOW_DOWNLOAD=true)

Low-level

Tool	Purpose
codesys_submit_job	Submit any action directly to the job queue
stage_existing_project	Copy/move project into standardized folder

4) Typical round-trip workflow

Import existing project into Cursor

1. read_project_inventory  → get tree + textual sources → populate codesys_tree/
2. read_device_io          → get devices, I/O channels, variable mappings → populate codesys_tree/

Edit locally

Edit .st, .gvl, .nvl, .type.st files under codesys_tree/ in Cursor.

Push changes back to VM project

3. sync_project (dry_run=true)   → preview what will change
4. sync_project (dry_run=false)  → apply all textual + IO mapping changes in one save
5. build_project                 → compile
6. download_to_device            → deploy to PLC

For individual changes, use write_pou or write_io_mapping directly.

5) Safety-first usage

• Start with dry_run=true for all mutating operations.
• Keep CODESYS_AGENT_ALLOW_DOWNLOAD=false while validating.
• Enable download only when target routing and credentials are verified.
• Close the CODESYS IDE on the VM before any write/push operations.

6) Local project layout

Every project in Codesys_Projects/projects/<name>/ uses this structure:

<project>/
├── config/project.json     # VM paths, profile, target device
├── codesys_tree/            # 1:1 mirror of CODESYS IDE tree
│   └── Device/
│       ├── Plc Logic/Application/
│       │   ├── POUs/PLC_PRG/PLC_PRG.program.st
│       │   ├── GVL/GVL.gvl
│       │   └── 3.Function Blocks/fb_boiler/fb_boiler.fb.st
│       └── EtherCAT_Master/EK1100/
│           ├── K1/K1.io_mapping.txt
│           └── K2/K2.io_mapping.txt
└── docs/

codesys_tree/ is the canonical source layout. It mirrors the hierarchical structure inside the CODESYS IDE so every folder and file maps 1:1 to a CODESYS tree node.

FAQ

Do we need to keep CODESYS IDE open?

• No. The agent launches CODESYS.exe with --noUI --runscript for all operations.
• Read operations (inventory, device I/O) work even if the IDE has the project open (uses readonly mode).
• Write operations (write_pou, sync_project, manage_device) require the IDE to have the project closed, because CODESYS project files are exclusively locked.
• A CODESYS installation and valid profile are still required on the VM.

Can we read existing CODESYS projects?

• Yes. Use read_project_inventory for sources and read_device_io for device/IO info.
• Sources are written into codesys_tree/ mirroring the exact CODESYS IDE hierarchy.

Can we modify device I/O mappings?

• Yes. Use write_io_mapping with device_path + param_id + variable.
• Or use sync_project with io_mappings for batch updates.
• Or import/export CSV via read_device_io(export_csv_path=...) and write_io_mapping(import_csv_path=...).

Can we add/remove devices?

• Yes. Use manage_device with operations like add, remove, update, rename, enable/disable, set_param.
• Device type/id/version values come from read_device_io output or the CODESYS device catalog.