ecockpit-mcp
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.
ecockpit-mcp
MCP (Model Context Protocol) server exposing e!COCKPIT PLC automation to LLM/AI editors: build, import, compile, online variable read, project snapshot, live-PLC download — as typed, schema-discoverable tools.
Self-contained: everything that runs on the e!COCKPIT machine ships in this
repo. The only external input is YOUR automation project (pointed at by
ECP_PROJECT_ROOT).
Disclaimer — independent tooling, not affiliated with, endorsed by, or sponsored by WAGO GmbH & Co. KG. "e!COCKPIT" and "WAGO" are trademarks of WAGO GmbH & Co. KG, used here solely to identify the platform this tooling operates on. WAGO has discontinued e!COCKPIT; this project targets existing installations.
Architecture
MCP client (ZCode etc.)
| streamable-http http://<host>:9777/mcp (bearer token; default)
| or stdio (--transport stdio, client-spawned)
v
src/ecockpit_mcp/server.py <- host Python 3.10+ (this repo)
| FILE PROTOCOL (local to the e!COCKPIT machine)
| tmp/ecockpit_cmd.json + _cmd_result.json + _watch.heartbeat
v
src/ecockpit_mcp/relay.py <- IronPython INSIDE e!COCKPIT (this repo;
| arm once per session: FILE -> Scripting
| -> Execute script file)
v exec per command
src/ecockpit_mcp/executor.py <- command implementations (this repo;
drives the open project via the
e!COCKPIT ScriptEngine)All three parts read ONE .env found next to the scripts (the search walks
up from the script's own directory — never the cwd — so it also finds a
repo-root .env in a checkout). The work dir holding the file-protocol
files and logs defaults to tmp/ next to the scripts (ECP_WORK_DIR
overrides).
The file protocol is intentionally simple: the in-instance side is
single-threaded IronPython inside a GUI, so transport latency is irrelevant
next to 15-60 s command durations, and atomic-rename files are crash-safe
and debuggable (cat tmp/ecockpit_cmd.json).
Related MCP server: RemoteConnect MCP Server
Your automation project
ECP_PROJECT_ROOT points at your automation project repo. The executor
expects:
plcopensrc/— exported PLCopen XML sources (Application.*.xml), auto-discovered one level deep (plcopensrc/<device>/works too); override withECP_XML_DIR.ecpproject file (optional — one under the project root is auto-discovered; otherwise the already-open project in e!COCKPIT is used)optional
.envkeys in THIS repo's.env:REMOVED_POUS(stale-object cleanup list),IGNORE_CODES(known-noise compiler codes),PLC_USER/PLC_PASS(PLC login for online commands),ECP_VERSION_POU(POU whosesAppVersionconstant names snapshots)
There is no built-in default for ECP_PROJECT_ROOT — the server and
executor are install-agnostic on purpose.
Git worktrees / switching projects (op=use)
The executor re-reads the .env per command (the in-instance relay
re-executes it every time), so editing ECP_PROJECT_ROOT /
ECP_XML_DIR is a valid switch. To switch without touching .env:
ecockpit_project_control op=use root=D:\path\to\worktree confirm=truevalidates the triplet — root exists,Application.*.xmldiscovered underplcopensrc/, exactly one.ecp(passecp=when there are several) — opens the.ecpas the primary project unlessopen=false, and persists it to<ECP_WORK_DIR>\ecockpit_active_project.json.The sidecar overrides
.envfor every later command (precedence: scriptargs > sidecar >.env> discovery). ExplicitECP_SNAPSHOTS_DIR/ECP_PROJECTS_DIRstay as configured.op=use_clear confirm=trueremoves the sidecar.Every
ecockpit_statusreports aproject_sourcesblock (active root, xml_dir,.ecp, source:sidecar/.env, open primary) and every build log header carries the same triplet — the silent open-project-from-A + import-XML-from-B mismatch cannot happen unnoticed (builds WARN when the open primary disagrees with the sidecar).Switches are sequential: one e!COCKPIT instance has one primary project and one set of single-writer protocol files — parallel worktrees are an engine limit, not an MCP one.
Quickstart
Prereqs: Windows with e!COCKPIT installed (the relay and executor run inside it), host Python 3.10+, and your automation project (above).
1. Install — from a checkout of this repo:
py -3 -m venv .venv # or any Python >= 3.10
.venv\Scripts\python.exe -m pip install -e .
copy .env.example .env # then edit: ECP_PROJECT_ROOT, PLC credspip install -e . pulls in the mcp dependency and puts the
ecockpit-mcp command on the venv PATH. (Script-only use without
installing: pip install -r requirements.txt is enough.)
.env keys — see .env.example for the full annotated list:
ECP_PROJECT_ROOT (required), ECP_MCP_HOST (default 127.0.0.1),
ECP_MCP_PORT (default 9777), ECP_MCP_TOKEN (required for non-loopback
binds), plus the project/PLC keys above. The .env is found next to the
scripts, then up to two parent levels — a repo-root .env works in a
checkout, and ECP_* environment variables override it.
2. Start the server (host side):
# long-lived daemon (local + remote editors), loopback by default
.venv\Scripts\ecockpit-mcp --transport http
# LAN exposure requires a token
.venv\Scripts\ecockpit-mcp --transport http --host 0.0.0.0 --token <secret>CLI flags --work-dir/--host/--port/--token override the .env.
3. Connect your editor (ZCode / any MCP client):
{
"mcpServers": {
"ecockpit": {
"url": "http://127.0.0.1:9777/mcp",
"headers": { "Authorization": "Bearer <token>" },
"timeoutMs": 1200000
}
}
}timeoutMs raises the client's per-call cap (default 30000 ms), which
otherwise kills long commands (build with a full XML re-import runs
60-120 s; rebuild up to 20 min) while the daemon keeps executing them.
Keep it at or above the largest timeout_s you will pass — daemon-side
per-command defaults top out at rebuild 1200 s. If a call does time
out client-side anyway, do NOT retry the command: it is still running
on the daemon. The timed-out tool result carries the command id, and
ecockpit_server_status shows what the engine is doing right now
(in_flight — id, cmd, age_s; or queued for a submitted-but-not-yet-
picked-up command) and the eventual result in last_result — poll
those and match by id instead of retrying.
4. Arm the relay — with your project open in e!COCKPIT, run once per
session: FILE -> Scripting -> Execute script file ->
src\ecockpit_mcp\relay.py. It then polls for commands until stopped
(e!COCKPIT's "Stop script", or create tmp\ecockpit_server.stop). Until it
is armed, every relay tool returns an ok:false payload with
"error": "not_armed" and the re-arm hint as its hint field — data you
can read, not a protocol error.
5. Verify — call the ecockpit_server_status tool from your editor, or
run the dev smoke client from the checkout (it talks real MCP: initialize,
tools/list, status, and refusal checks; PLC-touching steps are skipped
unless the relay is armed):
.venv\Scripts\python.exe smoke_client.pyTools
Every tool name carries the ecockpit_ prefix (ecockpit_build,
ecockpit_read, …) — a readable contract for clients that talk to
several MCP servers at once. (The bare pre-rename names build, read,
write, … were deprecated aliases for one release and are gone since
2026-11-09; configs must use the canonical names. The old
ecockpit_import spelling of ecockpit_importxml went with them.)
Security model — bearer token (mandatory off-loopback), loopback default, confirm-gated destructive operations, the online-commands-can-deploy caution, and credential handling — is documented in docs/security.md.
Build & project:
Tool | Notes |
| re-import + cleanup + compile; structured diagnostics ( |
| FULL rebuild ( |
| halves of build, standalone ( |
| PLCopen XML export to |
| project copy to |
| project/application/device info (no PLC login) |
Online (PLC):
Tool | Notes |
| online variable read ( |
| destructive — write/force values on the RUNNING PLC; confirm-gated, reads back after write |
| read-only — staged (prepared) values + currently forced variables |
| destructive — explicit login with online-change control ( |
| destructive — writes the SOURCE project to the PLC (not the compiled app); saves the project first |
| destructive — replaces the RUNNING PLC app; |
| destructive — stops the running PLC application |
| PLC logout ( |
CAUTION — every online command logs in via the online-change ladder
(read-only tools prefer OnlineChangeOption.Keep: login without
applying changes or downloading) but deploying commands may still
apply code deltas to the RUNNING application.
System object (the injected system global):
Tool | Notes |
|
|
| destructive — |
Project tree + ST authoring:
Tool | Notes |
|
|
| destructive — create pou/gvl/dut/interface/folder/method/property/action/transition, plus |
| read the ST declaration/implementation text |
| destructive — replace the whole declaration or implementation |
Task + symbol configuration:
Tool | Notes |
| inspect tasks (kind, priority, interval, watchdog, POUs) — read-only |
| destructive — create a task (kind/interval/priority/watchdog/POUs); creates the task configuration when missing |
| full signature + variable inventory ( |
| destructive — add the symbol configuration object |
| options read ( |
Device scan / communication / parameters:
Tool | Notes |
| gateway list, network scan (discovered targets), IP→CODESYS-address resolution — read-only |
| communication settings read / set IP via gateway ( |
| device identification ( |
| parameter |
| IO mapping inspection ( |
Application + project lifecycle:
Tool | Notes |
| is_active, is_uptodate, is_online_change_possible — read-only |
|
|
Project lifecycle + info:
Tool | Notes |
|
|
| destructive — PLC file rename/mkdir/rmdir (recursive) on the ScriptOnlineDevice — confirm-gated |
PLC file system (works via the ScriptOnlineDevice created by
online.create_online_device — the project-tree device object has no
file API):
Tool | Notes |
| list a PLC directory (the runtime root is |
| download a file from the PLC |
| destructive — upload a file onto the PLC |
| destructive — delete a PLC file |
| read the source project archive back from the PLC |
Libraries (global librarymanager / ILibManager — repository curation;
there is no per-application Library Manager scripting API in this build):
Tool | Notes |
| list installed libraries (version, company, namespace, dependencies, repo file path); paged — |
| find by display name (all matches + repository); |
| install a compiled-library file into a repository (default: first in search order); |
| destructive — remove a library from a repository; ambiguous names are refused unless |
| repositories in search order: name, root folder, editable, library count |
| destructive — register a new repository (folder must exist) |
| destructive — unregister a repository; |
| destructive — rename/relocate a repository |
| reorder the search order (first match wins) |
Diagnostics:
Tool | Notes |
| armed? heartbeat age, last result |
| scripting-API debugging aid: category map + active IGNORE_CODES filter |
| wipe the message store — call before a build for a fresh harvest |
All destructive tools (ecockpit_download, ecockpit_write,
ecockpit_stop, ecockpit_login, ecockpit_source_download,
ecockpit_lib_uninstall, ecockpit_repo_add, ecockpit_repo_remove,
ecockpit_repo_update) are confirm-gated at BOTH the MCP layer and the
executor and carry destructiveHint annotations.
ecockpit_build/ecockpit_compile/ecockpit_rebuild return harvest
(structured compiler messages) and log_tail inline on failure, so the
model usually needs no second read.
ScriptEngine API reference
docs/SCRIPTENGINE_API.md— distilled + live-verified reference for the e!COCKPIT ScriptEngine (IScriptApplication.build/rebuild, IScriptMessage structured fields, the getattr()-fails-on-interop-objects gotcha, project save/save_as semantics, online APIs). Source: the installedScriptEngine.chm.docs/SCRIPTENGINE_NOT_EXPOSED.md— what the CHM documents but these tools deliberately do not expose (full-audit inventory: 217 interfaces, ~580 methods / ~830 properties), with candidates for future tools.
Tool 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
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
Build, validate, test-run and publish AIOS workflows from Claude Code, Codex, Cursor or VS Code.
MCP facade over the Nebelus Construction API. ~48 tools give full agent build parity: create/update/probe agents, edit graphs, attach knowledge and vector stores, wire connectors, set governance policies and locked guardrails, enable grounding-trace, and read deployment wiring. Purpose-built for regulated industries: data residency is enforced per region (EU / GCC-KSA), with PII controls and an audit trail. Agents are created as drafts — no deploy tool is exposed over MCP by design; publishing happens in the Nebelus console.
Deploy and manage Jade Hosting projects from AI clients. Jade account and OAuth required.
Related MCP Servers
- AlicenseAqualityBmaintenanceAutomates the Sigmatek LASAL software suite for PLC and HMI engineering, enabling AI assistants to inspect projects, apply structural changes, compile, download to hardware, and control PLC runtime.2023210 npm2MIT
- AlicenseBqualityDmaintenanceEnables AI agents to discover, inspect, edit, rebuild, and save Schneider Electric RemoteConnect and SCADAPack x70 IEC logic projects, including program sections, hardware, variables, and Modbus configuration.631MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to automate CODESYS V3 PLC development, including project editing, builds, library and alarm management, online variable read/write/force operations, and CODESYS documentation search via MCP.4MIT
- AlicenseCqualityAmaintenanceEnables an AI agent to drive a Beckhoff TwinCAT 3 setup end to end: read and write live PLC variables and system state over ADS, manage files and processes on the target IPC, build and edit projects through the XAE automation interface, capture and analyze long-running signal recordings, run scripted test benches and TcUnit suites, and look up the official Beckhoff Infosys documentation. Runs as a single Python process on the engineering PC with read-only, guarded, and full safety modes plus human-in-the-loop confirmation for destructive operations.61711MIT