codesys-mcp-server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 withcodesys_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_applicationand 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.
v0.3.1 — cross-reference, refactoring and simulation (ported from Codesys-MCP-Master, MIT)
codesys_find_references: every use of an identifier in the project's textual code (POUs, methods, properties, actions, DUTs, GVLs, interfaces), with line/column and the qualifier in front of each hit (PLC_PRG.inPLC_PRG.bRun) - CODESYS's scripting API has no cross-reference call, so this reads every textual object with an ST lexer (comments, strings, pragmas and typed literals are skipped; matching is whole-identifier and case-insensitive like IEC 61131-3). Graphical bodies (FBD/LD/CFC/SFC) are reported asnot_searched_graphical.codesys_rename_symbol: rename an identifier project-wide AND the object of that name, rewriting the declaration header thatcodesys_rename_objectleaves stale. Dry run is the default; the call refuses reserved words, time-literal suffixes, and names already used anywhere in the project, rolls back on failure, and can be limited to object paths. Always dry-run first, then build after a real rename (references from libraries are invisible to the lexer).codesys_monitor_variables: sample variables of the running application over a time window (first/last/min/max/changes, optional raw samples); reuses the session ofcodesys_online_login.codesys_set_simulation_mode: read or set a device's simulation mode - the application then runs in CODESYS's built-in simulator instead of on the PLC (test without hardware). Refuses when the project has unsaved changes.codesys_list_device_repository: the device descriptions installed in the local repository, filtered by name/vendor/type.
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*inbridge/warm_projects.txt.Interfaces: create them empty (
codesys_create_interface) and add members withcodesys_create_member. Full-text interface declarations with METHOD/PROPERTY signatures do not parse, andcodesys_set_codeon 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_allsteps insidecodesys_batch(app.build()needs the primary project and fails inside a batch) - callcodesys_buildstandalone. Do not putclose_projectinside 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, runcodesys_clean_alland rebuild. Never change the type of an existing PERSISTENT variable; add new variables instead.remove_pouincodesys_configure_taskis 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_objectworks for objects created in the current warm session; objects loaded from disk may refuse removal (ScriptEngineremove()throws NullReference).get_compiler_versionis not available (no such ScriptEngine API on SP21 Patch 1).scan_network/device_reachableneed a configured gateway; a missing gateway is reported as an honest result, not an exception.The offline
boot_application_creategenerator may fail on SP21 Patch 1 even aftergenerate_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. The launcher (bridge/bridge_daemon.ps1) spawns the daemon and a companion monitor window fully detached via WMI;CB_MONITOR=0skips the monitor,CB_KEEP=1does not kill existing CODESYS processes first. Machine-specific paths go intobridge/bridge_daemon.local.ps1(git-ignored); by defaultCODESYS.exeis resolved fromCODESYS_EXEor a search underC:\Program Files\CODESYS.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 buildStart the HTTP server:
npm startOr start the stdio server:
npm run start:stdioBy 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.Build the project first:
npm install
npm run buildPrefer stdio transport for local agent integration.
Add the server to the client using the local build output:
claude mcp add --transport stdio codesys-docs -- node ./dist/src/cli.js --stdioIf the client needs HTTP instead, start the server and register the endpoint:
npm startclaude mcp add --transport http codesys-docs http://localhost:3000/mcpIf the agent can only work from a published package, use:
claude mcp add --transport stdio codesys-docs -- npx -y codesys-mcp-server --stdioFor Codex CLI:
codex mcp add codesys-docs -- node ./dist/src/cli.js --stdioQuick Start
npm install
cp .env.example .env
npm run build
npm startThe server listens on http://0.0.0.0:3000/mcp by default.
Docker
docker compose up --buildThe 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_docswithsourceMode: "pdf"orsourceMode: "all"list_codesys_pdfssearch_codesys_pdfsget_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
Variable | Default | Description |
|
| HTTP port. |
|
| Bind host. |
|
| Enables live official CODESYS page lookup. |
|
| Fetch timeout per official page. |
|
| In-memory cache TTL for official pages. |
|
| Enables text extraction/search for local PDFs. |
|
| Folder scanned for |
|
| Maximum extracted text stored per PDF. |
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:stdioAcceptance Checks
npm test
npm run build
curl http://localhost:3000/healthzTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Query your team's AI coding history and act on HypAware recommendations from any MCP client.
GitHub Copilot MCP: code, repo, PR, workflow tools for AI assistants.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA Model Context Protocol server that enables seamless interaction between MCP clients (like Claude Desktop) and CODESYS V3 programming environments, allowing automation of project management, POU creation, code editing, and compilation tasks.3,423 npm136MIT
- AlicenseNot gradedqualityDmaintenanceEnables CODESYS development assistance via MCP, including curated guidance, Structured Text writing help, local PDF search, and live official documentation lookup.1MIT
- FlicenseNot gradedqualityCmaintenanceMCP server that connects AI assistants to Siemens TIA Portal via the Openness API. AI-assisted PLC programming, project management, hardware configuration, cross-reference analysis, and deployment. 19 tools, 230 actions.64-
- FlicenseNot gradedqualityAmaintenanceMCP server for TwinCAT 3 PLC development enabling AI coding agents to build, configure, deploy, and debug TwinCAT PLC projects through a standard tool interface.2-