# 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.
- **224 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 **62 core tools of 224 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`.
## 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.