Control Expert MCP Server

An MCP server that connects AI agents (Claude Desktop, Claude Code, VS Code Copilot, or any MCP client) to a local EcoStruxure Control Expert (formerly Unity Pro) installation — so the AI can read, edit, and create PLC projects from scratch.

Inspired by tiaportal-mcp for Siemens TIA Portal. Where TIA Portal exposes the Openness API, Control Expert exposes the Unity Developer's Edition (UDE) COM automation server (PSBroker.PServerBroker) — this server drives it through pywin32 and exposes it as MCP tools over stdio.

AI agent (Claude, Copilot, ...) ──MCP/stdio──> control-expert-mcp ──COM──> Control Expert

What the AI can do

• Projects: create from scratch for any CPU in the hardware catalog (M340, M580, Premium, Quantum...), open/save .stu/.sta, import/export .xef/.zef

• Browse: tasks, sections, variables, DFB/DDT types, CPU/hardware info, build state

• Program: create/read/delete sections in ST, LD, FBD, SFC, IL; write logic by importing Control Expert XML (the AI reads an existing section's XML once and mirrors the schema — validated round-trip for all five languages)

• Hardware: walk the full bus → drop → rack → module topology, add/remove IO modules by catalog part number, change the CPU

• Modbus / DTMs (validated live on M580): browse the DTM topology, add slave DTMs (add_dtm("Modbus Device", ..., parent_dtm="BMEP58_ECPU_EXT") — the protocol id is Modbus and is auto-tried), set device IP addresses, read the scanner state (get_dtm_control_parameters), and add Modbus scan requests (read/write addresses + sizes) by editing the master DTM dataset through get_master_dtm_dataset / set_master_dtm_dataset — a ManagedModbusRequest template with the numbering rules is built into the tool description; a written scan line builds built_ok and shows up as a ModbusScanLine in the scanner config

• Networks (Premium/Quantum): create logical Ethernet networks and set their IP service configuration

• Variables: list/create/update/delete global variables incl. type, comment, address (%MW...), initial value

• Build: analyze and build the project, get the resulting build state

• UI: pop the Control Expert window open so a human can watch or take over, and open an animation table's editor live (open_animation_table) to watch values animate while the AI drives a test

• Online (opt-in): connect to PLC/simulator, download/upload, run/stop

• Live values (opt-in): read and write running PLC/simulator values over Modbus TCP (modbus_connect → read_tags/write_tags) — the UDE/COM API has no live tag access, so this is the channel for testing logic against a running controller (located %M/%MW tags; mirror unlocated DFB internals to %MW first)

Requirements

• Windows with EcoStruxure Control Expert (or Unity Pro) installed and licensed — tested against Control Expert 14.0, but any version that registers PSBroker.PServerBroker.1 should work (the UDE automation server ships with Control Expert itself; the separate UDE package is only needed for documentation)

• Python 3.10+ with pywin32

• The server must run on the same machine as Control Expert (DCOM remoting is possible but not configured here)

Install

cd control-expert-mcp
python -m venv .venv
.venv\Scripts\pip install -e .

Hook up an AI client

The server speaks MCP over stdio. Point your client at the venv's Python:

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (see samples/claude_desktop_config.json):

{
  "mcpServers": {
    "control-expert": {
      "command": "C:\\path\\to\\control-expert-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "control_expert_mcp"]
    }
  }
}

Claude Code

claude mcp add control-expert -- C:\path\to\control-expert-mcp\.venv\Scripts\python.exe -m control_expert_mcp

VS Code (GitHub Copilot agent mode)

.vscode/mcp.json (see samples/vscode-mcp.json):

{
  "servers": {
    "control-expert": {
      "type": "stdio",
      "command": "C:\\path\\to\\control-expert-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "control_expert_mcp"]
    }
  }
}

Tools

How the AI writes logic

Program sections are exchanged as Control Expert XML. An ST section looks like:

<STExchangeFile>
  <fileHeader company="Schneider Automation" product="Control Expert V14.0 - 190112"
              dateTime="date_and_time#2026-6-11-1:0:0" content="Structured source file"
              DTDVersion="41"></fileHeader>
  <contentHeader name="Project" version="0.0.000"></contentHeader>
  <program>
    <identProgram name="Logic01" type="section" task="MAST"></identProgram>
    <STSource>
IF StartButton AND NOT StopButton THEN
    MotorRun := TRUE;
ELSE
    MotorRun := FALSE;
END_IF;
    </STSource>
  </program>
</STExchangeFile>

import_xml(kind="section", xml_content=...) creates the section if it doesn't exist, or deletes-and-replaces it on conflict. The agent should declare referenced variables first (create_variable) or include a <dataBlock>, then build_project to validate.

Online tools (live PLC / simulator) — disabled by default

Tools that touch a controller (plc_connect, plc_transfer, plc_command, ...) are not registered unless you set the environment variable:

CE_MCP_ENABLE_ONLINE=1

Starting/stopping a PLC or downloading an application affects the physical process. Only enable this on test benches or with the simulator, and keep a human in the loop.

Simulator commissioning (validated end to end): launch the PLC simulator first — start_simulator or PLC_Simulator\sim.exe from the Control Expert install (it sits in the tray) — then plc_setup_connection("simulator", "127.0.0.1") → plc_connect("simulator") → plc_transfer("pc_to_plc") → plc_command("run"). The project must build clean (built_ok) before download. plc_state reports connection + run/stop and whether PC == PLC.

Known limitation: a freshly started simulator with no station loaded (plc_state = no_conf) rejects plc_transfer with "Family check failed" — the API download (unlike the Control Expert GUI's) requires the sim to already have a station of a matching family. Seed it once by transferring any project from the Control Expert GUI (PLC → Simulation Mode → Connect → Transfer); the loaded station persists while sim.exe runs, and all API downloads work from then on (stop the PLC first — transfer to a running PLC fails).

Live values over Modbus TCP (validated end to end)

The UDE/COM automation API serves the project database — it has no live tag-value read/write (animation tables only render in the GUI; IVariable exposes only the offline initial value). Live values go over the CPU's Modbus TCP server instead — the same channel SCADA/Vijeo use:

modbus_connect(host="127.0.0.1")          # the sim's Modbus server; or a real CPU IP, port 502
read_tags("EMFM1FLOW, RESIDUAL2CLTHSP, %MW0, %MW2:REAL")
write_tags({"RESIDUAL2CLTHSP": 4.0, "%MX100.0": true})

• Tags are global variable names (address + IEC type resolved from the project) or explicit addresses with optional :TYPE (%MW86, %MW2:REAL, %MW70:UDINT, %M3, %MW10.2 bit). Decoding is type-driven (INT/UINT, DINT/UDINT, REAL, BOOL coil/word-bit).

• Only LOCATED %M/%MW tags are reachable. Unlocated DFB internals (e.g. Pump1.Running) must be mirrored to %MW/%M in the program first (see the test_logic_live prompt).

• 32-bit REAL/DINT use Schneider low-word-first order by default; pass word_order="high_first" if a server differs.

• The Control Expert simulator exposes a Modbus server on 127.0.0.1:502, so the whole read/write test loop works against the sim — no hardware required.

Prompts (guided workflows)

The server ships MCP prompts (src/control_expert_mcp/prompts.py) — reusable recipes that encode the validated flows and their non-obvious gotchas so a client doesn't rediscover them by trial and error. In Claude Code they appear as /mcp__control-expert__<name> slash commands; other MCP clients list them in their prompt picker.

Extending the server

When you add a tool or capability, also add (or extend) an MCP prompt in prompts.py that walks a client through using it. This is a project convention, not an afterthought: a good prompt turns an hour of trial-and-error into one slash command.

Write a prompt for anything a client cannot guess from the tool description alone — an environment flag (CE_MCP_ENABLE_ONLINE), a manual GUI step (the simulator family-check seed), an ordering constraint (stop the PLC before transfer), or an addressing rule (located-only Modbus, low-word-first REALs). Rules of thumb:

• Each new workflow → a prompt; each new tool → at least a mention in a relevant prompt.

• Put the gotcha in the prompt text explicitly (the steps that cost you time while building it).

• Mirror the validated sequence (tool names + argument shapes), and reference related prompts by name.

• Keep the standing orientation in the server instructions string short; put step-by-step recipes in prompts.

Troubleshooting

• Catalog object not found on new_project — the CPU part number/version must exactly match the hardware catalog of your Control Expert version (spacing matters: BMX P34 2020, firmware like 02.70 is required).

• application object reference is not found in the catalog on add_io_module — same rule for modules: the catalog version is mandatory (02.00 for most M340 IO modules, 01.00 for racks/power supplies).

• new_project fails with a bare Exception occurred for a CPU family — your Control Expert license/DTM library probably doesn't include that platform. The error carries no description; test the same CPU in the Control Expert GUI to confirm.

• add_dtm says "protocol Id parameter is empty or invalid" / "Impossible to create a new DTM object" — slave DTMs need the FDT protocol name as protocol_id (Modbus for the generic Modbus TCP device; the server auto-tries Modbus and EtherNet/IP when empty) and a device_type_name that exactly matches the DTM catalog (Modbus Device). List the catalog names with tools/list_dtm_catalog.py.

• set_master_dtm_dataset crashes the server (RPC failed) — almost always malformed request XML; in particular requestUniqueID must be a fresh GUID, not an integer. Mirror the validated template in the tool description exactly.

• Write access mode is already reserved by another client — Control Expert (the GUI) or another automation client has the project open for writing. Close it there first. The server holds one write token per session by design.

• Broker creation fails — Control Expert isn't installed, or its COM registration is broken (re-register by repairing the installation).

• First call is slow — open_project/new_project start the Unity server process and can take 30–120 s for large projects. Configure generous tool timeouts in your client.

• Import fails with Invalid file — the XML doesn't match the exchange schema. Export a similar object first (read_section, export_xml) and mirror its structure, including fileHeader/contentHeader.

Architecture notes

• All COM calls run on a single dedicated STA worker thread (COM apartment affinity); MCP tool calls are marshalled onto it (the dispatcher is reentrant — nested bridge calls on the worker thread execute directly).

• Hardware and DTM objects expose their members on secondary dual interfaces (IProject3, IConfiguration2, IBus, IModule, IPServerDtm*, ...) that the default dispinterface doesn't include. The bridge QIs each object with IIDs harvested from HKCR\Interface and wraps the result as IDispatch (_qi), which is the only way to reach DTMRoot, InternalBuses, AddChild, etc. from late-bound clients.

• The write-access token (app.Project(1)) is acquired once per session and cached; failed-call tracebacks are stripped so they can't pin COM references and deadlock ProjectClose.

• Project is a parameterized COM property — it is invoked with explicit DISPATCH_PROPERTYGET flags because pywin32 dynamic dispatch can't call it.

• Import temp files get the extension matching the XML root element (STExchangeFile → .xst, VariablesExchangeFile → .xsy, ...) because Control Expert picks the parser from the extension.

• Enum constants (languages, export options, PLC commands...) were extracted from PServer.tlb — see src/control_expert_mcp/constants.py.

Disclaimer

Not affiliated with Schneider Electric. The UDE automation interface is provided by Schneider "as is" and is no longer commercialized; this project drives it at your own risk. Never point online tools at production equipment without qualified supervision.