summary: 项目总览：这套 MCP 是什么、怎么装（含给同事的一句话）、版本说明与安全默认值
kind: entry
when: 想知道这个项目能干什么、怎么安装时
env: none

TIA Portal Openness MCP — 多版本（V18 / V20 / V21）

本项目为 TIA Portal Openness MCP，以 MIT 许可证发布，独立维护，支持 TIA Portal V18 / V20 / V21 三个版本构建。

在 Windows + TIA Portal V18 / V20 / V21 下，通过 MCP（stdio） 驱动博途：建项目、加硬件、生成 PLC（Tag/UDT/DB/SCL/LAD）、生成 Classic / Comfort / Unified HMI 画面与标签、编译诊断、保存。包内含 已编译运行时、Skill、模板、能力矩阵、手册。不要求另行克隆源码仓库——下载本仓库根目录的 zip 解压即用。

快速上手（3 步）

照这 3 步，把 MCP 客户端连上你的 TIA Portal V18。

1. 准备：装好 TIA Portal V18 + .NET Framework 4.8；把当前 Windows 用户加入本地组 Siemens TIA Openness，注销重登一次。
2. 下载解压：在本仓库页面点 Code → Download ZIP（或 git clone），解压到任意目录。
3. 挂载 MCP：在 MCP 客户端（WorkBuddy / Cursor / VS Code / Claude Desktop 等）配置里，把 command 指向解压目录内的
   tools\tiaportal-mcp\src\TiaMcpServer\bin-v18\Release\net48\TiaMcpServer.exe，
   args 传 ["--tia-major-version","18","--logging","0"]，信任该连接器并重启客户端。连接器将暴露 204 个 V18 安全工具。

版本说明（V18 / V20 / V21）

本仓库同时维护 V18 / V20 / V21 三个构建（三个 csproj，输出同名 TiaMcpServer.exe，按输出目录 bin-v18 / bin-v20 / bin 区分）。其中 V18 构建做了如下兼容性处理：

• WinCC Unified HMI 在 V18 不可用：V18 的 Openness 全安装不含 Siemens.Engineering.HmiUnified 程序集。相关 23 个 Unified HMI 工具已用 #if !TIA_V18 条件编译守卫在 V18 构建中隐藏（方法体保留，仅不注册为 MCP 工具，从 tools/list 中消失）。
• 暴露工具数：连接器实测 204 个 V18 安全工具（基线 232 − 28 个守卫工具）；V20/V21 构建暴露完整工具集。
• VersionControl（VCI）在 V18 不可用：V18 的 Siemens.Engineering 程序集不含 MappedObject / ExportObject / ConnectObject / GetSupportedFileFormats，VCI 为 V20+ 能力，其 5 个工具同样以 #if !TIA_V18 在 V18 构建中隐藏。
• 深度审计结论：除上述 28 个工具（23 个 Unified HMI + 5 个 VCI）外，其余暴露工具在 V18 全部安全可用；V20 专属文档工具（Export/Import*Documents）在 V18 构建中仅以引导提示暴露、不可调用。
• HMI 自动化路径：V18 下请走 Classic / Comfort HMI 工具族；Unified 需求须使用 V20/V21 构建。

安装前须知

前提条件

会改动什么（均可回滚）

• 写 5 个客户端的 MCP 配置（只改 mcpServers["tia-portal"] 一项，其它条目与顶层键不动，改前备份 *.bak）：
  WorkBuddy / Claude Desktop / Claude Code / Cursor / VS Code —— 只处理已存在的配置文件
• 若下载：安装目录 %USERPROFILE%\tia-mcp

建议先自检（只读，不改任何东西；会告诉你缺什么、哪条下载通道能通）：

powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-WebRequest -UseBasicParsing 'https://codeload.github.com/1748477582/tia-portal-openness-mcp/zip/refs/heads/master' -OutFile .\tia-mcp.zip; Expand-Archive .\tia-mcp.zip -DestinationPath .\tia-mcp-pkg -Force; & .\tia-mcp-pkg\tia-portal-openness-mcp-master\bootstrap.ps1 -Check"

回滚

powershell -ExecutionPolicy Bypass -File .\install-mcp.ps1 -Remove   # 只删 tia-portal 条目

再删掉 %USERPROFILE%\tia-mcp 即可完全还原（配置侧还有 .bak）。

离线安装（机器完全不能上网时）

1. 在能上网的机器打开 https://github.com/1748477582/tia-portal-openness-mcp/archive/refs/heads/master.zip 下载
2. 拷到目标机器，解压到 %USERPROFILE%\tia-mcp
3. 在解压目录运行 powershell -ExecutionPolicy Bypass -File install-mcp.ps1 -TiaMajorVersion 20

一行安装（复制即用）

推荐写法：整包下载 → 解压 → 调安装器。不依赖 raw.githubusercontent.com（很多网络封它），也不用 iex
（企业组策略常禁）。把下面整段复制给对方，粘给他的 AI 或直接在 PowerShell 里执行：

powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-WebRequest -UseBasicParsing 'https://codeload.github.com/1748477582/tia-portal-openness-mcp/zip/refs/heads/master' -OutFile .\tia-mcp.zip; Expand-Archive .\tia-mcp.zip -DestinationPath .\tia-mcp-pkg -Force; & .\tia-mcp-pkg\tia-portal-openness-mcp-master\install-mcp.ps1 -TiaMajorVersion 20"

把末尾的 20 换成要用的版本（18 / 20 / 21）。去掉 -TiaMajorVersion 20 则会在终端里让你确认探测结果并选版本
——脚本不会替你选。

若对方网络能访问 raw.githubusercontent.com，也可以用更短的一行（bootstrap.ps1 会自动挑可用通道）：

powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-WebRequest -UseBasicParsing 'https://raw.githubusercontent.com/1748477582/tia-portal-openness-mcp/master/bootstrap.ps1' -OutFile .\tia-bootstrap.ps1; & .\tia-bootstrap.ps1"

装完重启 AI 客户端；之后想换版本，在安装目录（默认 %USERPROFILE%\tia-mcp）运行 switch-version.ps1。

安装（给同事 / 新机器）

接手这个仓库（换电脑 / 换 agent）先读 AGENTS.md：入口、必读顺序、自检命令、硬规则。
想找"有没有现成的文档/脚本"，查 docs/INDEX.md（自动生成，50+ 项，带"何时用/需要什么环境"）。

最快的方式：把上面那条一行命令复制给对方（或粘给他的 AI）。

如果要给对方 AI 一段自然语言指令（而不是一条命令），用这段：

帮我装 TIA Portal MCP：执行
powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-WebRequest -UseBasicParsing 'https://raw.githubusercontent.com/1748477582/tia-portal-openness-mcp/master/bootstrap.ps1' -OutFile .\tia-bootstrap.ps1; & .\tia-bootstrap.ps1"
它会先列出本机装了哪些 TIA —— 把列表贴给我，我告诉你用哪个版本，然后你再用 -Version <版本> 跑一次。
装完提醒我重启客户端。

或自己动手（PowerShell，整包解压后运行，不需要管理员权限）：

# 交互安装：先列出本机装了哪些 TIA → 让你确认探测是否正确 → 让你选用哪个版本
powershell -ExecutionPolicy Bypass -File install-mcp.ps1

# 只看计划（不写文件）；非交互时必须显式给版本，否则脚本拒绝——不替你猜
powershell -ExecutionPolicy Bypass -File install-mcp.ps1 -DryRun -FollowOpenTia

# 非交互/脚本化：固定某个版本，或跟随当前打开的 TIA
powershell -ExecutionPolicy Bypass -File install-mcp.ps1 -TiaMajorVersion 20
powershell -ExecutionPolicy Bypass -File install-mcp.ps1 -FollowOpenTia

# 装完以后随时换版本（只改 TIA_MCP_VERSION，不碰其它配置）
powershell -ExecutionPolicy Bypass -File switch-version.ps1

# 只要约 40 个核心工具 / 卸载
powershell -ExecutionPolicy Bypass -File install-mcp.ps1 -Lite
powershell -ExecutionPolicy Bypass -File install-mcp.ps1 -Client cursor -Remove

支持的客户端：WorkBuddy（~/.workbuddy/mcp.json）、Claude Desktop、Claude Code、Cursor、VS Code——
默认只处理本机确实装了的那些。改配置前自动备份为 *.bak，重复执行是幂等的。

需要 Windows + TIA Portal V18/V20/V21（含 Openness 选项）；装了多个 TIA 版本时默认用最高版本，
想指定加 -TiaMajorVersion 18。只装一个版本时会自动钉住该版本——启动器在"没打开 TIA"时兜底写死 V18，
不钉会加载错误的构建（V18 目录不存在 → 起不来）。也可以双击 配置MCP-v18.bat / 配置MCP-v20.bat / 配置MCP.bat（按版本选）。

更细的说明（含常见卡点）见 同事安装_给Agent的一句话.md。

安全默认值与自省工具（2.5.0 起）

• FindTools(query, limit)（L0）：按能力词检索全部工具名与描述，返回精确工具名、参数签名与风险标注
  （read-only / reads the project, writes a file / writes or overwrites engineering data /
  RISK changes CPU, deletes data or closes project - call by name）。不改变对外通告的工具列表，是兜底而非流程必经步骤。
• 反射桥不再通向 Portal / 工程：通过 InvokeObject / InvokeService 调用 TiaPortal 或 Project 的方法
  （Close / Dispose / Save / SaveAs 等）一律拒绝并指向 CloseProject / Disconnect / SaveProject / OpenProject。
  此前 InvokeObject(portal, "Dispose", allowWrite=true) 可以关掉用户开着的 TIA（2026-09-24 事故的同一类路径）。
• WritePlcSclSourceFile 不再静默覆盖：目标文件已存在且内容不同 ⇒ 报错并要求显式 overwrite=true（内容相同仍幂等成功）。
• 8 个危险默认值改为"省略即安全"：overwrite（5 个批量导入工具）与 autoCreateGroup / autoCreate（3 个分组/归类工具）
  默认改为 false；CloseProject / Disconnect 的 saveBeforeClose=true 保持不变（那本来就是安全方向）。
• 启动时清理陈旧临时产物：%TEMP% 下本服务器自建的、带唯一后缀且超过 24 小时的导出/回读/备份目录会被清除；
  固定名目录（如 tia_mcp_scl）与他人进程的文件一律不动。

上手步骤

1. 环境准备

   • .NET Framework 4.8、TIA Portal V18 已安装；
   • 当前用户加入 Siemens TIA Openness 本地组，注销重登；
   • 定位博途安装根（任选其一）：
     a) 启动 exe 时传 --tia-portal-location "C:/Program Files/Siemens/Automation/Portal V18"（推荐，非标准安装位置必用）；
     b) 用户环境变量 TiaPortalLocation 指向博途安装根；
     c) 让程序自动从注册表读取。
   • 首次连接时在 TIA 弹窗中授权 Openness。

2. 挂载 MCP（手动配置，最稳）
   复制压缩包内的 .mcp.json 片段（或参考下例），把 command 指向本包内的 V18 exe：

   {
     "mcpServers": {
       "tia-portal": {
         "command": "C:/path/to/unzip/tools/tiaportal-mcp/src/TiaMcpServer/bin-v18/Release/net48/TiaMcpServer.exe",
         "args": ["--tia-major-version", "18", "--logging", "0"],
         "env": { "TiaPortalLocation": "C:/Program Files/Siemens/Automation/Portal V18" }
       }
     }
   }
   

   （若使用受管 MCP 客户端，升级 TiaMcpServer.exe 前需先在连接器配置中将 disabled 设为 true 释放文件锁，复制完成后再恢复。同款 exe 也支持 TiaMcpServer.exe config 尝试自动发现并写入宿主配置，手动配置更稳。）

3. 首次调用顺序

   • Bootstrap → Connect → OpenProject（或 CreateProject）→ GetProjectTree，从树中读取真实的 PLC_xxx / HMI_RT_xxx 路径再继续。

能力范围与边界

可做：工程与硬件组态、PROFINET、PLC 声明式导入（Tag/UDT/DB/SCL/LAD）、Classic / Comfort HMI 连接/变量/画面、交叉引用与影响面分析、批量分组与自动分类、编译诊断、保存。

V18 下不可做：

• WinCC Unified HMI（23 个工具已隐藏，V18 Openness 不含 HmiUnified 程序集）——需 V20/V21。
• S7DCL 人类可读 SCL 文本导出（Export/Import*Documents 系列为 V20+ 专属，本构建仅以引导提示暴露、不可调用）。可改走 ExportBlockSourceUtf8 + RegenerateBlockFromSource（SimaticML XML，强制 UTF-8+BOM 编码安全）。

包内不含：西门子安装介质、现场导出工程、业务专用工艺。

版本对照

构建（如需自行编译）

三个 csproj 对应三个 TIA 版本，输出目录区分：

:: V18（隐藏 28 个工具：23 Unified HMI + 5 VCI，共 204 个）
dotnet build TiaMcpServer.V18.csproj -c Release ^
  -p:TiaPortalLocation="C:/Program Files/Siemens/Automation/Portal V18" ^
  -p:BaseOutputPath=bin-v18/ -p:BaseIntermediateOutputPath=obj-v18/

:: V20（单体会话程序集）
dotnet build TiaMcpServer.V20.csproj -c Release ^
  -p:TiaPortalLocation="D:/Program Files/Siemens/Automation/Portal V20" ^
  -p:BaseOutputPath=bin-v20/ -p:BaseIntermediateOutputPath=obj-v20/

:: V21（拆分程序集）
dotnet build TiaMcpServer.csproj -c Release

TiaMcpServer.V18.csproj 已定义 TIA_V18 编译符号，自动隐藏 Unified HMI 工具。

交付内容

master 分支根目录提供：

（本仓库不发布单独的 `TIA_Portal_Openness_MCP.zip` 资产，也没有 GitHub Release —— 早期文档里的那个 zip 已不存在。）

压缩包内含：已编译运行时 bin-v18/、源码 src/、文档 docs/、模板 templates/、Skill、能力矩阵 manifest/、配置 .mcp.json、以及更详细的 README.md 与 LICENSE。解压后所有文档与模板均在包内，无需另行克隆源码仓库。

本仓库直接包含完整源码树（tools/tiaportal-mcp/src/，三个 csproj：V18 / V20 / V21），另有预置运行时 runtime/。下载方式：Code → Download ZIP，或 git clone。

文档地图（压缩包内）

常见问题

Q：连接器只显示部分工具 / 看不到某个工具？
属于客户端工具描述符/缓存问题，不是交付包裁剪能力；重启客户端或清空工具缓存即可。运行时权威列表以 tools/list 为准。

Q：为什么没有 WinCC Unified？
TIA Portal V18 的 Openness 全安装不含 Siemens.Engineering.HmiUnified 程序集，Unified HMI 工具在 V18 构建中被 #if !TIA_V18 守卫隐藏。V18 下请走 Classic / Comfort HMI 工具族；Unified 需求使用 V20/V21 构建。

Q：升级 TiaMcpServer.exe 时被「文件被占用」？
受管 MCP 连接器的进程由宿主托管，会被立即重生。升级前先在连接器配置中将 disabled 设为 true 释放文件锁，复制完成后再恢复。

Q：与 IDE 无关吗？
是。凡支持 MCP 的客户端（WorkBuddy、Cursor、VS Code、Claude Desktop、自研 HTTP 客户端等）均可使用同一 TiaMcpServer.exe。

许可证

本项目以 MIT 许可证发布，版权声明见 LICENSE。