TIA_Portal_Openness_MCP

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: [email protected] · 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 [email protected] 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 normal session only needs L0 + L1.

Requirements

• Windows + .NET Framework 4.8
• TIA Portal V20 or V21 installed
• Current user added to the Siemens TIA Openness local group (re-login after)

Quick Start

1. Locate the portal install root (one of):

   • pass --tia-portal-location "D:\app\TIA20\Portal V20" when launching (recommended for non-default installs);
   • set the TiaPortalLocation user environment variable;
   • let it auto-read HKLM\SOFTWARE\Siemens\Automation\_InstalledSW\TIAP{20|21}\TIA_Opns\Path. With multiple versions installed, pass --tia-major-version 20 (or 21) explicitly.

2. Mount the MCP — one command, fully automatic. Double-click 配置MCP.bat in the bundle root (V20: 配置MCP-v20.bat), or run tia.cmd config.

   Engine exe locations by distribution: Release zip → tools\tiaportal-mcp\src\TiaMcpServer\bin\Release\net48\ (V21) / ...\bin-v20\Release\net48\ (V20); git clone → runtime\v21\ (V20 runtime is not shipped in git — download the Release zip). All launcher scripts resolve both layouts automatically.

   It self-discovers everything: its own absolute path, the installed TIA Portal (registry) and version, and the version-matching exe (V20/V21 picked for you) — then writes the tia-portal entry into every AI host detected on this machine: Claude Desktop / Claude Code / Cursor / VS Code (existing config backed up as .bak, other servers preserved). Restart the AI client to load it. Options: config --host vscode (or claude|claude-code|cursor), config --print to copy a snippet manually. The server lists 65 core tools of 235 by default (about 57 KB instead of 196 KB of tool schema per turn) so weaker models are not drowned and VS Code/Copilot’s 128-tool cap and Windsurf’s 100 never trip. Nothing is lost: the model reaches every other tool on demand with FindTools("plain words") + CallTool(name, argumentsJson), and the handshake instructions tell it so. Pass config --full to list the whole tool surface instead. If anything fails to connect, run tia.cmd doctor (v2.2.8): a one-shot environment check (TIA install, exe/version match, Openness group, host registration) with the exact fix per problem; --fix auto-adds the Openness group. Since v2.2.7 the exe also self-routes: if it was built for a different TIA major version than the machine has, it transparently re-execs the matching sibling exe — grabbing the “wrong” exe no longer crashes. Manual fallback: copy the snippet from cursor-mcp.example.json, replace REPLACE_ME with this bundle’s root, pick the exe path by TIA version; for non-default installs add "--tia-portal-location","<root>","--tia-major-version","<20|21>" to args.

3. First call sequence: Bootstrap → Connect → OpenProject (or CreateProject) → GetProjectTree, then read the real PLC_* / HMI_RT_* paths from the tree before continuing.

Offline validation (no TIA needed)

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Validate-Bundle.ps1

Checks runtime presence, blueprint file completeness, tool-count consistency, and that PLC/HMI JSON parse. Add -Strict for tighter manifest/matrix comparison.

Build from source

The full source lives under tools/tiaportal-mcp/src/TiaMcpServer (51 .cs).

# V21 (split DLLs)
dotnet build tools/tiaportal-mcp/src/TiaMcpServer/TiaMcpServer.csproj -c Release
# V20 (monolithic DLL) — clean intermediates first if you just built the other target
dotnet build tools/tiaportal-mcp/src/TiaMcpServer/TiaMcpServer.V20.csproj -c Release

Capabilities & boundaries

Can do: projects & hardware, PROFINET, declarative PLC import, LAD XML import, WinCC Unified connections / tags (absolute addressing) / screens / button Down·Up / dynamization, compile-and-diagnose, save.

Not bundled: Siemens install media, field projects, business-specific technology. reference/ is style/instruction reference only. See notBundled in manifest/package-manifest.json. For what Openness cannot do, see 手册/openness-limitations.md.

Read-only mode: start the server with --read-only (or TIA_MCP_READ_ONLY=1) and every call that could change the project, the CPU or the open project is refused before it runs — listed tools, CallTool and the HTTP bridge alike. Reads, exports (written to — and overwriting — the path you give, never the project) and connect / open / close stay available; an older project is not upgraded on open, and an export blocked by an online PLC is not taken offline for you. The flag covers the MCP server only (CLI verbs refuse to run with it). The lite / full profile only decides which tools are listed; it is not a write protection.

Version branches & contributing

master is always the stable line for TIA Portal V20 / V21; its default behaviour never changes to accommodate older releases. Earlier TIA Portal / Openness versions live on their own branches, and contributions there are welcome:

How to contribute

• Send a fix or adaptation for an older release to its own branch (a V17 change goes to v17), not to master.
• v21 / v20 are official lines: anything that applies to both versions still goes to master. Only use a version branch when a fix would change the other version’s behaviour or depends on an API that exists in one version only — that way shared code stays in one place.
• Older Openness APIs and block XML differ substantially, so branching lets each version be validated independently without destabilising main-line users.
• If a fix turns out to be general and stable, a small follow-up PR back to master is very welcome.
• Please do not commit: TIA project files (.apXX), bin / obj, logs, screenshots, backups, machine-specific absolute paths, or scratch test projects.

Want to adopt one of the version branches? Just say so in an Issue.

See CONTRIBUTING.md for the full workflow, and SECURITY.md for reporting vulnerabilities.

Documentation map

Standard loop (abbreviated)

Bootstrap → Connect → CreateProject → AddDeviceWithFallback → AddHardwareCatalogDeviceWithProbe
→ ConnectDeviceNodesToProfinetSubnet → GetProjectTree → ValidateAutomationContext
→ PlcBuildAndImport(dryRun=true per item) → PlcBuildAndImport(dryRun=false in import order)
→ CompileAndDiagnosePlc → EnsureUnifiedHmiConnection → EnsureUnifiedHmiTagTable → EnsureUnifiedHmiTag
→ EnsureUnifiedHmiScreen → ApplyUnifiedHmiScreenDesignJson → BindUnifiedHmiTagDynamization
→ EnsureUnifiedHmiButtonAction → SaveProject → Disconnect

Contact

• Bugs / feature requests: please open an Issue so others hitting the same problem can find it.
• TIA 助手 trial, custom development, partnerships: [email protected]
• Desktop edition: aeenhance.com

Siemens, TIA Portal, SIMATIC, STEP 7 and WinCC are trademarks of Siemens AG. This project and TIA 助手 are independently developed third-party tools with no affiliation with, agency for, or authorization from Siemens AG.