TIA_Portal_Openness_MCP
Drive Siemens TIA Portal V20/V21 (STEP 7, WinCC Unified) from any MCP client — create projects, generate PLC & HMI, compile & diagnose. Prebuilt runtime, no Openness coding required.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/bulaofen0036-coder--tia-portal-openness-mcp)HTML
<a href="/listings/bulaofen0036-coder--tia-portal-openness-mcp"><img src="/api/listings/bulaofen0036-coder--tia-portal-openness-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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 **~55 core tools of 222 by default** (~8,500 instead of ~38,800 tokens of 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.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 11 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "name": "tia-portal-openness-mcp",
- "owner": { "name": "bulaofen", "email": "bulaofen0036@gmail.com" },
- "plugins": [
- {
- "name": "tia-portal-openness-mcp",
- "source": "./",
- "description": "Siemens TIA Portal Openness automation MCP — bundled V21 server + skill, one-command install."
- }
- ]
- }
README.md · README · 304 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 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](CHANGELOG.md) (this README no longer hardcodes a version).
- **English** · [中文](README.zh-CN.md)
- > **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.
- [](LICENSE) [](https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/releases) [](https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/actions/workflows/validate.yml)
- > **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)](https://aeenhance.com/)** —
- > 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](https://aeenhance.com/) · [1-minute demo](https://aeenhance.com/#demo) · Trial: **bulaofen0036@gmail.com** · [Comparison ↓](#tia-助手-tia-assist--the-desktop-edition)
- 
- 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](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](#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`](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
- [](https://aeenhance.com/)
- 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)](https://aeenhance.com/)**:
- 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.)*
- 
- <sub>↑ 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 →](https://aeenhance.com/#demo)</sub>
- | | Open-source MCP (this repo) | TIA 助手 (desktop edition) |
- |---|---|---|
- | Form | MCP server + `tia` CLI, driven by your own AI client | Windows desktop app, **no install — unzip and run**; V20 / V21 engines bundled and picked automatically |
- | AI | Bring your own (Cursor / Claude Desktop / VS Code …) | **Built-in AI assistant**; DeepSeek, Qwen, Kimi, Zhipu or any OpenAI-compatible API — or a local **Ollama** model, fully offline, project data never leaves the plant |
- | Write safety | Up to your client | **Every write waits for your approval**; irreversible operations (e.g. deleting blocks) are confirmed separately; hash-chained audit log |
- | Online values | Read-only (S7 absolute addresses / OPC UA) | **No TIA Portal needed** — symbolic read/write over S7CommPlus; writes off by default, forced read-back when enabled |
- | Trend recording | — | Record, overlay/split, export and replay CSV |
- | Environment check | `tia.cmd doctor` (CLI) | Graphical per-item check of runtimes / Openness allow-list / user group with the fix for each, one-click diagnostic bundle |
- | License | MIT, free | Commercial — **free trial available** |
- **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](https://aeenhance.com/assistant) · [Online debugging](https://aeenhance.com/online) · [Safety boundaries](https://aeenhance.com/security) · [Manual](https://aeenhance.com/manual) · [Get started](https://aeenhance.com/start)
- > 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
- 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`).
- ```powershell
- # 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:
- | Branch | Target version | Maintenance |
- |--------|----------------|-------------|
- | `master` | TIA Portal V20 / V21 | Official main line (day-to-day work lands here) |
- | `v21` | TIA Portal V21 / Openness V21 | Official; forked from master, V21-only adaptations |
- | `v20` | TIA Portal V20 / Openness V20 | Official; forked from master, V20-only adaptations |
- | `v19` | TIA Portal V19 / Openness V19 | Community |
- | `v18` | TIA Portal V18 / Openness V18 | Community |
- | `v17` | TIA Portal V17 / Openness V17 | Community |
- | `v16` | TIA Portal V16 / Openness V16 | Community |
- **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](CONTRIBUTING.md) for the full workflow, and
- [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
- ## Documentation map
- | Path | What |
- |------|------|
- | `tools/tiaportal-mcp/skill/SKILL.md` | **Primary spec**: tool layers, parameter traps, Unified HMI schema, LAD/SCL boundaries |
- | `manifest/tools-list.json` | Static tool names/layers (runtime authority is `tools/list` after connect) |
- | `docs/tool-capability-matrix.md` | Capability matrix |
- | `docs/full-project-generation-runbook.md` | End-to-end project generation |
- | `docs/scl-instruction-library.md` / `docs/lad-instruction-library.md` | SCL / LAD instruction libraries |
- | `docs/hmi-connection-driver-matrix.md` | Communication-driver selection by CPU family |
- | `手册/quickstart.md` | English quick start |
- | `手册/TIA_NL_INTENT_RECIPES.md` | Natural-language → tool-sequence recipes |
- ## Standard loop (abbreviated)
- ```text
- 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](https://github.com/bulaofen0036-coder/TIA_Portal_Openness_MCP/issues) so others hitting the same problem can find it.
- - **TIA 助手 trial, custom development, partnerships**: **bulaofen0036@gmail.com**
- - Desktop edition: **[aeenhance.com](https://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.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.