CODESYS MCP Server

A Model Context Protocol server for CODESYS Development System V3. It gives MCP clients curated CODESYS guidance, Structured Text writing help, searchable local PDF documentation, and optional live lookup of allowlisted official CODESYS pages.

The server can run over HTTP at /mcp or over stdio for direct CLI and agent integration. Official pages are summarized and cited rather than copied into the project. Primary official sources include CODESYS Online Help and CODESYS Examples.

Tools

• search_codesys_docs: search curated and/or official CODESYS guidance.

• get_codesys_topic: explain a known topic such as POUs, function blocks, timers, tasks, variables, libraries, debugging, or Structured Text.

• codesys_writing_guidance: provide practical CODESYS and Structured Text design guidance for a requested task.

• list_codesys_pdfs: list PDF documents available in the configured PDF folder.

• search_codesys_pdfs: search text extracted from local PDF documents.

• get_codesys_pdf: return extracted text from a specific local PDF document.

• get_codesys_page: fetch the full text content of any allowlisted CODESYS documentation URL.

• crawl_codesys_help: crawl and index the CODESYS help site for searchable documentation.

Project automation bridge (works directly on .project files via the CODESYS ScriptEngine):

• codesys_project_open / codesys_project_info: open a project headlessly and inspect basic info.

• codesys_list_objects / codesys_get_object: list the project tree and read declaration/implementation ST text of any POU, DUT, GVL, or action.

• codesys_create_pou: create a PROGRAM / FUNCTION_BLOCK / FUNCTION with optional ST declaration and implementation text.

• codesys_create_member: add an action, method, or property to an existing POU or interface.

• codesys_create_interface: create an empty INTERFACE (members are added with codesys_create_member).

• codesys_create_dut / codesys_create_gvl: create data unit types and global variable lists.

• codesys_set_code: replace the declaration or implementation text of an existing object (never on an interface declaration - see limitations below).

• codesys_save_project / codesys_close_project: save the project; close it in the warm session and release the file lock for the GUI.

v0.3.0 — project lifecycle and device toolchain (ported from Codesys-MCP-SP21-plus, MIT)

• Multi-application: codesys_list_applications, codesys_set_active_application, codesys_create_project, codesys_list_open_projects.

• Object tree: codesys_rename_object, codesys_move_object, codesys_dump_pou_code (bulk-read all ST code in one call), codesys_set_exclude_from_build, codesys_signature_crc, codesys_grant_object_access.

• PLCopenXML exchange: codesys_export_plcopen_xml, codesys_import_plcopen_xml.

• Task configuration: codesys_list_tasks, codesys_configure_task (create/reconfigure tasks, add POU calls).

• Devices: codesys_add_device, codesys_device_info, codesys_list_device_parameters, codesys_set_device_parameter, codesys_set_device_state, codesys_device_reachable, codesys_device_rebind, codesys_device_user_add, codesys_scan_network, codesys_io_mappings_csv.

• Build actions: codesys_application_build_action (generate_code/rebuild/clean), codesys_online_change_check, codesys_get_compiler_version, codesys_set_compiler_version_newest, codesys_clean_all.

• Project files: codesys_save_project_as, codesys_save_project_archive.

• Online lifecycle (require codesys_online_login/codesys_download_application and a running PLC runtime): codesys_application_state, codesys_application_start_stop, codesys_application_reset, codesys_boot_application_create, codesys_plc_file_list, codesys_plc_file_delete, codesys_plc_file_transfer, codesys_source_download, codesys_source_upload.

• Symbol configuration (OPC UA): codesys_symbol_config_create, codesys_symbol_config_list, codesys_symbol_config_set_access, codesys_symbol_config_settings_get / _set, codesys_symbol_config_export_xsd.

• Network variables (NVL): codesys_nvl_sender_set, codesys_nvl_receiver_create.

Known SP21 Patch 1 limitations (verified empirically)

• Text writes (codesys_set_code, create-with-text) require the project to be the primary project in the ScriptEngine session. The bridge promotes/demotes automatically; the warm daemon marks the working project primary via * in bridge/warm_projects.txt.

• Interfaces: create them empty (codesys_create_interface) and add members with codesys_create_member. Full-text interface declarations with METHOD/PROPERTY signatures do not parse, and codesys_set_code on an interface declaration (even a comment) corrupts the object ("interface definition not found" on build). Interface members are child objects; edit them individually.

• Batch limits: do not put build/clean_all steps inside codesys_batch (app.build() needs the primary project and fails inside a batch) - call codesys_build standalone. Do not put close_project inside a batch either: it closes the batch's own project handle and breaks the remaining steps.

• Build verdicts: trust the compiler summary line ("0 errors"), not the raw return value of app.build() (always None). Incremental builds can hide errors - after changing the type of a PERSISTENT variable or an interface method, run codesys_clean_all and rebuild. Never change the type of an existing PERSISTENT variable; add new variables instead.

• remove_pou in codesys_configure_task is not supported: pous.remove() is a silent no-op and task objects cannot be deleted via the API. The op returns an honest error; remove POU calls in the CODESYS GUI.

• Deleting task-tree objects (tasks, Task Configuration) is not possible via the API at all.

• delete_object works for objects created in the current warm session; objects loaded from disk may refuse removal (ScriptEngine remove() throws NullReference).

• get_compiler_version is not available (no such ScriptEngine API on SP21 Patch 1).

• scan_network / device_reachable need a configured gateway; a missing gateway is reported as an honest result, not an exception.

• The offline boot_application_create generator may fail on SP21 Patch 1 even after generate_code (reported as an honest error).

How the project bridge works

Each project tool call writes a task file, starts CODESYS.exe --noUI --runscript=bridge/bridge.py (requires the CODESYS ScriptEngine, included with the IDE), executes the operation, saves and closes the project, and returns the result as JSON. Notes:

• The target project must not be open in the CODESYS GUI at the same time (file lock).

• Each call takes roughly 10–30 s because a headless CODESYS instance starts per call.

• With the optional warm daemon (bridge/bridge_daemon.cmd) the project stays open in a background CODESYS instance and calls take ~1–3 s. The daemon is also what the MCP plugin uses when available.

• Configure via env: CODESYS_EXE, CODESYS_PROFILE, CODESYS_BRIDGE_DIR, CODESYS_BRIDGE_TIMEOUT_MS (see .env.example).

Related MCP server: CODESYS MCP Server

What It Does

• Searches curated CODESYS guidance for concepts, syntax, and workflow help.

• Explains common CODESYS topics such as POUs, function blocks, timers, tasks, variables, libraries, debugging, and Structured Text.

• Provides practical Structured Text and project-structure guidance.

• Searches local PDF manuals and notes placed in docs/pdfs/.

• Fetches and summarizes allowlisted official CODESYS documentation pages.

• Crawls the official help site to build a searchable index.

Install For A Human

Use this when you want to run the server yourself on your machine.

Prerequisites:

• Node.js 20 or newer

• npm

From a fresh clone:

npm install
cp .env.example .env
npm run build

Start the HTTP server:

npm start

Or start the stdio server:

npm run start:stdio

By default, the HTTP server listens on http://0.0.0.0:3000/mcp.

Install For An LLM Or Agent

AI agent? Read agent.md — it contains the complete, step-by-step self-installation guide written specifically for you. Start there.

Use this section when an LLM is being instructed to connect itself to the server as an MCP client.

Suggested instruction to give the LLM:

Read agent.md in the repository root. It contains the exact steps to install this MCP server into yourself.

1. Build the project first:

npm install
npm run build

2. Prefer stdio transport for local agent integration.

3. Add the server to the client using the local build output:

claude mcp add --transport stdio codesys-docs -- node ./dist/src/cli.js --stdio

4. If the client needs HTTP instead, start the server and register the endpoint:

npm start

claude mcp add --transport http codesys-docs http://localhost:3000/mcp

5. If the agent can only work from a published package, use:

claude mcp add --transport stdio codesys-docs -- npx -y codesys-mcp-server --stdio

For Codex CLI:

codex mcp add codesys-docs -- node ./dist/src/cli.js --stdio

Quick Start

npm install
cp .env.example .env
npm run build
npm start

The server listens on http://0.0.0.0:3000/mcp by default.

Docker

docker compose up --build

The compose file mounts ./docs/pdfs into the container as read-only, so you can add PDFs locally without rebuilding the image.

PDF Folder

Put CODESYS manuals, vendor PDFs, project notes, datasheets, or exported documentation in:

docs/pdfs/

The MCP server extracts text from .pdf files in that folder and makes them available through:

• search_codesys_docs with sourceMode: "pdf" or sourceMode: "all"

• list_codesys_pdfs

• search_codesys_pdfs

• get_codesys_pdf

PDF text extraction is best for searchable text PDFs. Scanned image-only PDFs may return little or no content unless OCR has already been applied. Extracted text may omit diagrams, screenshots, formatting, and some tables, so important engineering details should be verified against the original PDF.

Configuration

CLI Usage

# HTTP server (default)
node dist/src/cli.js
npm start

# Stdio server (for Claude Code / Codex CLI MCP integration)
node dist/src/cli.js --stdio
npm run start:stdio

Acceptance Checks

npm test
npm run build
curl http://localhost:3000/healthz