TIA Portal MCP Server (V20 + V21 · S7DCL · CLI · read-only online monitoring · one-click config · Doctor)

Current version: see the Release badge below and CHANGELOG.md (this README no longer hardcodes a version).

English · 中文

v2.0 — the same exe is also a declarative CLI (tia). Any AI emits a YAML/JSON spec, any engineer runs one command (tia gen spec.yaml) — no MCP client required. Verbs: gen / patch / compile / describe / export / import / prewarm / schema / version. Exit code 0/1/2. See docs/CLI_quickstart.md. The MCP server behaviour is unchanged.

Free & open (MIT). The server runs with no license key — there is no license-enforcement code at all.

🖥️ Don't want to wire up an MCP client yourself? Try TIA 助手 (TIA Assist) — the desktop edition built on this engine: unzip and run, built-in AI assistant, and every write to your project waits for your approval first. 👉 aeenhance.com · 1-minute demo · Trial: bulaofen0036@gmail.com · Comparison ↓

Drive Siemens TIA Portal V20 or V21 from any MCP client (stdio or HTTP): create projects, add hardware, generate PLC objects (Tag / UDT / DB / SCL / LAD), build WinCC Unified screens and events, compile-and-diagnose, and save — all through natural-language tool calls. The bundle ships prebuilt runtimes, a Skill spec, a static tool list, a capability matrix, PLC/HMI templates, one-shot project blueprints, and a manual. No separate source clone required to run.

Works with any MCP-capable client — Cursor, VS Code, Claude Desktop, or your own HTTP client — using the same TiaMcpServer.exe.

🆕 v2.5.0 — put a TIA Portal project under Git (Version Control Interface)

TIA Portal projects are binary, so Git cannot diff them — which is why "version control" in this field has long meant a pile of dated Save As folders. The V21 Version Control Interface maps a project onto an ordinary folder, one text file per block, so it can be diffed, committed and reviewed. This release wraps the whole round-trip into a few commands — you never have to click anything inside the TIA Portal UI.

One sentence to your AI client is enough:

Put the current project under Git, use D:\repos\my-plc as the workspace

It creates the workspace → maps the whole project automatically (hundreds of blocks in one command, no manual ticking) → exports the text, and you git commit. Later, to see what changed:

GetVersionControlStatus(changedOnly=true)
→ A3_4_Hoist | Unequal        ← per block, not per file

• Covered: FC / FB / OB / DB, PLC tag tables, UDTs — the whole software side. Hardware configuration and know-how-protected blocks are not covered by the VCI; the tool reports them explicitly instead of skipping them silently.
• A block must compile before it can be exported (a TIA limitation); change detection is unaffected and works even on unsaved edits.
• Companion tools/vci-watch/: after each successful compile it auto-exports, writes the CHANGELOG and runs git commit — the engineer does nothing.

📖 Full usage and the three behaviours you must know → docs/version-control-git.md

⚡ Fastest start (3 steps, no coding — CLI path)

First time? No MCP client, no code. Once TIA is installed, these 3 steps generate your first project in minutes. (Wiring an AI client like Cursor / Claude Desktop over MCP instead? See Quick Start below.)

1. Prepare: install TIA Portal V20 or V21 + .NET Framework 4.8; add your Windows user to the local Siemens TIA Openness group and log off/on once (the group is not effective until re-login — the single most common blocker). Use the exe matching your installed version — the bundle root ships tia.cmd (V21) / tia-v20.cmd (V20); all other paths are auto-resolved.
   • Health-check first: run tia.cmd doctor (V20: tia-v20.cmd doctor) once after install — it checks TIA install / exe-version match / Openness group / host registration and prints the exact fix per problem (--fix auto-adds the group).
2. Prewarm (optional, recommended): double-click scripts\预热.bat and leave the window open. It keeps one headless TIA resident so every later command connects in ~1s (without it, each run cold-starts ~3 min). Press Ctrl+C to close.
3. Generate a project: drag a ready-made template templates\project-blueprints\scaffold_spec_motor.json (or scaffold_spec_start_stop.json) onto scripts\生成工程.bat — it creates the project → adds PLC/HMI → builds blocks → compiles → saves in one shot. Exit code 0 means success.
   • To customize: have any AI emit a spec per docs/AI_spec_prompt.md (YAML or JSON), then drag it onto 生成工程.bat.
   • CLI equivalent: add the bundle root to PATH, then tia gen <spec> (start with --dry-run for an offline check).

TIA 助手 (TIA Assist) — the desktop edition

This repository is the engine: you bring your own AI client (Cursor, Claude, VS Code…) and mount it. If you'd rather open an app and start working — or hand it to colleagues and commissioning engineers who have never heard of MCP — the author also ships TIA 助手 (TIA Assist): the same engine inside a Windows desktop app, with the AI assistant, online monitoring and trend recording built into the UI. (The UI and website are currently Chinese-only.)

↑ Real screen capture (demo project): asked to write a duty/standby rotation FB for two pumps, it hit 4 compile warnings on the first build and fixed them itself down to 0 errors / 0 warnings — pausing for a human "Yes" before every write. Watch the full recording →

Try it: email bulaofen0036@gmail.com with your TIA Portal version (V20 / V21) and what you want to try → get the trial package, run it, send back the machine code and receive a license key. The safest first run: let it explain your own project read-only and check whether it got it right. More: AI assistant · Online debugging · Safety boundaries · Manual · Get started

Both run the same engine: bugs fixed here are fixed there too, and issues reported here help both.

Highlights

• Stability-first public generation (v0.0.39). PlcBuildAndImport now returns CapabilityDecision, CapabilityWarnings, and RecommendedNextActions; ApplyUnifiedHmiScreenDesignJson(strict=true) fails when any HMI property write fails; EnsureUnifiedHmiTag(requireVerifiedBinding=true) requires readback as SymbolicVerified or AbsoluteVerified.
• Dual-version support (V20 + V21). Two separate executables, not interchangeable: V21 binds the split DLLs (Siemens.Engineering.Base/Step7/…), V20 binds the monolithic Siemens.Engineering.dll.
  • V21 → tools/tiaportal-mcp/src/TiaMcpServer/bin/Release/net48/TiaMcpServer.exe
  • V20 → tools/tiaportal-mcp/src/TiaMcpServer/bin-v20/Release/net48/TiaMcpServer.exe
• Version-safe imports. Generated Openness XML is normalized to the connected portal version on import, so a V20 portal no longer rejects blocks with "engineering version 'V21' is not supported".
• S7DCL textual format. ExportAsDocuments / ExportBlocksAsDocuments / ImportFromDocuments / ImportBlocksFromDocuments read/write the diff-friendly SIMATIC SD text format (.s7dcl + .s7res) on V20+ and are flagged PREFERRED on V21+. The SimaticML XML chain remains for backward compatibility.
• 235 tools across project, hardware, PLC, HMI, and online operations, layered [L0]/[L1]/[L2] so a nor