Skip to content
Back to search

tiaportal-mcp

A MCP server for Siemens TIA Portal

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

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/heilingbrunner/tiaportal-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/heilingbrunner/tiaportal-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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/heilingbrunner--tiaportal-mcp/badge.svg)](/listings/heilingbrunner--tiaportal-mcp)

HTML

<a href="/listings/heilingbrunner--tiaportal-mcp"><img src="/api/listings/heilingbrunner--tiaportal-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

README.md · README · 712 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.

  1. # TIA-Portal MCP-Server
  2. A MCP server which connects to Siemens TIA Portal.
  3. ## Resources
  4. - [TIA Portal Openness API Overview](https://docs.tia.siemens.cloud/r/en-us/v21/tia-portal-openness-api-for-automation-of-engineering-workflows/tia-portal-openness-api)
  5. - [TIA Portal Openness API Documentation](https://docs.tia.siemens.cloud/r/en-us/v21/tia-portal-openness-api-for-automation-of-engineering-workflows)
  6. - [TIA Portal Openness API for automation of engineering workflows](https://docs.tia.siemens.cloud/r/en-us/v21/tia-portal-openness-api-for-automation-of-engineering-workflows)
  7. - [TIA Portal Openness API for automation of engineering workflows - Export/Import Documentation](https://docs.tia.siemens.cloud/r/en-us/v21/tia-portal-openness-api-for-automation-of-engineering-workflows/export/import)
  8. ## Features
  9. - Connect to a TIA Portal instance
  10. - Browse and interact with TIA Portal projects
  11. - Perform basic project operations from within VS Code
  12. - Read the full PLC software: program blocks, PLC data types, tags and constants, watch and
  13. force tables, external source files, and cross references
  14. - Optionally create, rename, delete, move and import project objects (see [Write mode](#write-mode))
  15. ## Command Line Arguments
  16. | Argument | Description |
  17. | ------------------------- | ----------------------------------------------------------------------------------------- |
  18. | `--tia-major-version <n>` | TIA Portal major version to bind against. Default `21`. |
  19. | `--project-path <file>` | Preset for the `path` argument of `OpenProject` / `OpenTiaProject`. See below. |
  20. | `--software-path <path>` | Preset for the `softwarePath` tool argument, e.g. `PLC_1`. See below. |
  21. | `--export-path <path>` | Preset for the `exportPath` tool argument. See below. |
  22. | `--logging <1\|2\|3>` | `1` stderr, `2` debug output, `3` Windows event log. Omit for no logging. |
  23. | `--doctor` | Print the environment report and exit without starting the MCP server. |
  24. | `--keep-structure` | Flag: preset for the `keepStructure` argument of `TiaInit` (written to `tia.json`). |
  25. | `--with-dependencies` | Flag: preset for the `withDependencies` argument of `GetSourceBlock` and `GetSourceType`. |
  26. | `--allow-write` | Register the project-mutating tools. Omitted by default; see below. |
  27. | `--preserve-path` | Deprecated name of `--keep-structure`, still accepted; `--doctor` shows when it is used. |
  28. | `--force-presets` | Deprecated, no effect: every preset is binding now. `--doctor` shows when it is used. |
  29. ## Presetting tool arguments
  30. `softwarePath` and `exportPath` appear in many tools, `path` (the project file) in
  31. `OpenProject` and `OpenTiaProject`. Set them once in the `args`
  32. of the MCP server entry in your client's JSON configuration and the model no longer has to pass them:
  33. ```json
  34. "args": ["--project-path", "D:\\Projects\\Plant\\Plant.ap21", "--software-path", "PLC_1", "--export-path", "D:\\Export"]
  35. ```
  36. - Which option becomes which argument (tools and prompts alike; a test checks this for every tool and prompt):
  37. | Option | Argument | Used by |
  38. | --------------------- | ------------------ | ---------------------------------------------------------------------------- |
  39. | `--project-path` | `path` | `OpenProject`, `OpenTiaProject`, `TiaConnect`, `TiaInit` |
  40. | `--software-path` | `softwarePath` | every tool and prompt with a PLC software path |
  41. | `--export-path` | `exportPath` | every export / pull tool, `GetExportFormats`, `TiaPush*`, `TiaInit` |
  42. | `--export-path` | `importPath` | `OverwritePlcProgram`, `ImportHardware`, `PreviewImport`, `ImportWatchTable` |
  43. | `--keep-structure` | `keepStructure` | `TiaInit` |
  44. | `--with-dependencies` | `withDependencies` | `GetSourceBlock`, `GetSourceType` |
  45. `--tia-major-version`, `--logging`, `--doctor` and `--allow-write` configure the server itself and are not tool
  46. arguments; `--preserve-path` and `--force-presets` are deprecated.
  47. - **Every preset is binding.** A preset argument is removed from `tools/list` and from the prompt arguments, and a
  48. call that still sends it is overwritten with the preset. The model can neither forget nor change what your
  49. configuration sets, so it cannot write into another folder (for example an invented staging folder next to the
  50. export folder) or open another project. `OpenProject` can only open the `--project-path` project.
  51. - `importPath` (`OverwritePlcProgram`, `ImportHardware`, `PreviewImport`, `ImportWatchTable`) follows
  52. `--export-path`: a push reads the tree a pull wrote.
  53. - Without a preset nothing changes: the argument stays required and the model supplies it.
  54. - `GetState` lists the binding values in `Presets` (and the names in `ForcedPresets`, kept for older clients).
  55. - A single `--software-path` pins every call to that PLC, so it only fits a project with one PLC. For several PLCs
  56. leave `--software-path` out and the model passes `softwarePath` per call.
  57. - `--force-presets` (earlier opt-in for exactly this) is deprecated and has no effect any more; it is still accepted so
  58. existing configurations keep working, and `--doctor` lists it as `--force-presets (deprecated, ...) = used`.
  59. - `exportPath` / `importPath` is the base directory shared by all PLCs. Every export and folder-based
  60. import works below `<exportPath>/<softwarePath>/`, e.g. `D:\Export\Group1\PLC_1\Program blocks\...`,
  61. `...\PLC data types\...`, `...\PLC tags\...` and `...\Watch and force tables\...` (the folder names of the
  62. project tree in the interface language of TIA Portal); each `/` in `softwarePath` is a folder level. Imports that
  63. take the full path of a single file are unaffected.
  64. - Prompts (slash commands) use the presets too: an argument with a preset is not listed and is filled in. In a slash
  65. command, type only the arguments that are still listed.
  66. - This fixes the arguments you can configure, it is not a sandbox: the `filePath` / `sourcePath` of the single-file
  67. tools, `newProjectPath` of `SaveAsProject` and the names inside `blockPath` are not restricted.
  68. ## Write mode
  69. The server is read-only unless it is started with `--allow-write`.
  70. - Without the flag the 51 project-mutating tools are **not registered at all**, so they never
  71. appear in `tools/list`. A model cannot call what it cannot see, and the tool list stays small.
  72. - With the flag they are registered and annotated `destructiveHint: true`, so a client can still
  73. prompt before each call.
  74. - `GetState` and the `--doctor` report both expose `AllowWrite`, so a client can tell whether the
  75. tools are missing by configuration rather than by version.
  76. - Write operations change the project **in memory only**. Every write response says so and names
  77. the tool that persists it: `SaveProject`, or `SaveSession` when a multiuser local session is open.
  78. Export tools are intentionally *not* gated. `ExportBlock`, `ExportTagTable`, `ExportWatchTable`
  79. and friends only write files on the machine running the server; they never modify the project.
  80. They are annotated `destructiveHint: true` because they can overwrite files on disk.
  81. To enable write mode, add the argument to your client configuration, for example
  82. `"args": ["--allow-write"]`.
  83. ## Tools
  84. Read-only tools (71) are always available.
  85. | Area | Tools |
  86. | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  87. | Portal and state | `GetPortals`, `Connect`, `Disconnect`, `GetState`, `Doctor` |
  88. | Project and session | `GetProject`, `OpenProject`, `SaveProject`, `SaveAsProject`, `CloseProject` |
  89. | Devices | `GetProjectTree`, `GetDevices`, `GetDeviceInfo`, `GetDeviceItemInfo` |
  90. | PLC software | `GetSoftwareInfo`, `GetSoftwareTree`, `CompilePlcSoftware`, `CompileCodeBlock`, `ExportOpcUaXml` |
  91. | Blocks | `GetBlocks`, `GetBlockInfo`, `GetBlocksWithHierarchy`, `ExportBlock` (one block), `ExportBlocks` (by regex); format from `tia.json` |
  92. | Types | `GetTypes`, `GetTypeInfo`, `ExportType` (one type), `ExportTypes` (by regex); format from `tia.json` |
  93. | Tags and constants | `GetTagTables`, `GetTagTableInfo`, `GetTags`, `GetTagInfo`, `GetConstants`, `ExportTagTable` (one table), `ExportTagTables` (by regex); always XML |
  94. | Watch and force tables | `GetWatchTables`, `GetWatchTableInfo`, `GetForceTables`, `ExportWatchTable` (one table), `ExportWatchTables` (by regex), `ExportForceTable`; always XML |
  95. | External sources | `GetExternalSources`, `GetExternalSourceInfo` |
  96. | Read source inline | `GetXmlBlock`, `GetXmlType`, `GetSourceBlock`, `GetSourceType`, `GetDocumentsBlock`, `GetDocumentsType` |
  97. | Cross references | `GetCrossReferences` |
  98. | Libraries | `GetOpenLibraries`, `GetReferencedLibraries` |
  99. | Multiuser | `GetMarkedObjects`, `CheckIsUpToDate` |
  100. | Understand and read (comfort) | `GetPlcSummary`, `ResolveObjectPath`, `WhereUsed`, `FindInCode`, `GetBlockInterface`, `PreviewImport`, `OpenTiaProject` |
  101. | Whole PLC program | `ExportPlcProgram` (format per object type from `tia.json`, see below), `GetExportFormats` |
  102. | Git-like connect and pull | `TiaInit`, `TiaConnect`, `TiaPull`, `TiaPullBlocks`, `TiaPullTypes`, `TiaPullTagTables`, `TiaPullBlock`, `TiaPullType`, `TiaPullTagTable`, `TiaPullWatchTables`, `TiaPullWatchTable`, `TiaPullForceTable` (see "`tia` porcelain commands" below) |
  103. Write tools (40) require `--allow-write`.
  104. | Area | Tools |
  105. | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
  106. | Block and type groups | `CreateBlockGroup`, `DeleteBlockGroup`, `CreateTypeGroup`, `DeleteTypeGroup` |
  107. | Blocks and types | `DeleteBlock`, `RenameBlock`, `DeleteType`, `RenameType`, `CreateFB`, `CreateInstanceDB` |
  108. | Copy and move | `CopyBlock`, `MoveBlock`, `CopyType`, `MoveType` |
  109. | Tag tables | `CreateTagTable`, `DeleteTagTable`, `RenameTagTable`, `CreateTagTableGroup`, `DeleteTagTableGroup` |
  110. | Tags and constants | `CreateTag`, `UpdateTag`, `DeleteTag`, `CreateUserConstant`, `UpdateUserConstant`, `DeleteUserConstant` |
  111. | Watch tables | `CreateWatchTable`, `RenameWatchTable`, `DeleteWatchTable`, `CreateWatchTableGroup`, `DeleteWatchTableGroup`, `ImportWatchTable` |
  112. | External sources | `CreateExternalSourceFromFile`, `DeleteExternalSource`, `CreateExternalSourceGroup`, `DeleteExternalSourceGroup` |
  113. | Whole PLC program | `OverwritePlcProgram`, `ImportPlcProgramChanges` (sources, XML and SIMATIC SD documents, preview by default, see below) |
  114. | Git-like push | `TiaPush`, `TiaPushPreview` (see "`tia` porcelain commands" below) |
  115. | Hardware (AML) | `ExportHardware`, `TiaPullHardware`; with `--allow-write` also `ImportHardware`, `TiaPushHardware` |
  116. | Multiuser | `CommitChanges` (commits the local session to the server and closes the session) |
  117. `GetSoftwareTree` accepts a `sections` argument - any comma separated subset of
  118. `blocks,types,tags,watch,sources`, default `all` - to keep the output small on a large PLC.
  119. `GetCrossReferences` accepts `maxDepth` (1-3, default 1) for the same reason.
  120. Paths used by these tools are **root-relative**: `1_Tests/FC_Block_1`, not
  121. `Program blocks/1_Tests/FC_Block_1`. Use `GetProjectTree` and `GetSoftwareTree` to discover them.
  122. ### `tia.json`: the export formats of TIA Portal
  123. TIA Portal exports each kind of object in the format set under **Options > Settings > Version control interface >
  124. Export formats**: SIMATIC SD documents (`.s7dcl`, `.s7res`), SimaticML (`.xml`) or a source file. Openness cannot
  125. read that setting (the settings tree it offers has no export formats), so the server keeps the formats in a plain,
  126. visible file at the root of the export folder:
  127. ```
  128. <exportPath>/tia.json
  129. ```
  130. It is one file for all PLCs below `<exportPath>`, because the setting is global. It is meant to be kept and committed
  131. together with the export, so everyone who works with the folder uses the same formats.
  132. **You normally do not write it.** `tia init` sets it up (see "`tia` porcelain commands"). The first time a tool needs it
  133. and it does not exist, the server creates it with the defaults TIA Portal offers for a new workspace:
  134. ```json
  135. {
  136. "args": {
  137. ...
  138. },
  139. "version-control-interface": {
  140. "code-blocks-LAD": "SIMATIC SD(.s7dcl, .s7res)",
  141. "code-blocks-FBD": "SIMATIC SD(.s7dcl, .s7res)",
  142. "code-blocks-SCL": "SIMATIC SD(.s7dcl, .s7res)",
  143. "code-blocks-STL": ".awl",
  144. "code-blocks-LAD-STL": ".xml",
  145. "code-blocks-GRAPH": ".xml",
  146. "data-blocks": "SIMATIC SD(.s7dcl, .s7res)",
  147. "safety-data-blocks-F-DBs": "SIMATIC SD(.s7dcl, .s7res)",
  148. "plc-data-types": "SIMATIC SD(.s7dcl, .s7res)",
  149. "plc-tables": ".xml",
  150. "f-compliant-plc-data-types-UDT": "SIMATIC SD(.s7dcl, .s7res)",
  151. "technology-objects": ".xml"
  152. }
  153. }
  154. ```
  155. The file can also carry an optional `args` section for other programs that work with the same TIA Portal project.
  156. Its keys follow the server arguments `--project-path`, `--software-path`, `--export-path` and `--keep-structure`
  157. (`"keep-structure": "true"` and `"with-ui": "true"` are written only when checked; `tia init` renames an
  158. old `"preserve-path"` key to `"keep-structure"`, `"with-user-interface"` to `"with-ui"` and `"project"` to `"project-path"`, and keeps their values). **The server does not
  159. read it**; only `tia init` writes it (the automatic creation does not) and every tool keeps it as it is:
  160. ```json
  161. {
  162. "args": {
  163. "project-path": "C:\\Projects\\Plant\\Plant.ap21",
  164. "software-path": "PLC_1",
  165. "export-path": "C:\\Projects\\Plant\\export"
  166. },
  167. "version-control-interface": {
  168. "code-blocks-LAD": "SIMATIC SD(.s7dcl, .s7res)"
  169. }
  170. }
  171. ```
  172. All keys use hyphens instead of spaces. A file with the old spaced keys (`version control interface`,
  173. `code blocks-LAD`, ...) is not read any more: rename the keys.
  174. Available file formats per object type; the first one listed is the default of a new file:
  175. | Key | Available formats |
  176. | -------------------------------- | -------------------------------------------- |
  177. | `code-blocks-LAD` | `SIMATIC SD(.s7dcl, .s7res)`, `.xml` |
  178. | `code-blocks-FBD` | `SIMATIC SD(.s7dcl, .s7res)`, `.xml` |
  179. | `code-blocks-SCL` | `SIMATIC SD(.s7dcl, .s7res)`, `.scl`, `.xml` |
  180. | `code-blocks-STL` | `.awl`, `.xml` |
  181. | `code-blocks-LAD-STL` | `.xml` |
  182. | `code-blocks-GRAPH` | `.xml` |
  183. | `data-blocks` | `SIMATIC SD(.s7dcl, .s7res)`, `.db`, `.xml` |
  184. | `safety-data-blocks-F-DBs` | `SIMATIC SD(.s7dcl, .s7res)`, `.xml` |
  185. | `plc-data-types` | `SIMATIC SD(.s7dcl, .s7res)`, `.udt`, `.xml` |
  186. | `plc-tables` | `.xml` |
  187. | `f-compliant-plc-data-types-UDT` | `SIMATIC SD(.s7dcl, .s7res)`, `.xml` |
  188. | `technology-objects` | `.xml` |
  189. **Fixed format.** `code-blocks-GRAPH`, `plc-tables` and `technology-objects` offer only `.xml`, so their export file
  190. format is fixed. `code-blocks-GRAPH` is read (a missing key also exports `.xml`), while `plc-tables` and
  191. `technology-objects` are listed only so the file names every object type; no tool reads them.
  192. **Check a created file.** The server cannot see your TIA Portal settings, so the defaults may differ from yours. The
  193. response of `ExportPlcProgram` (`Notes` and the message) and of `GetExportFormats` (`Created`, `Hint`) says when the
  194. file was just created and asks you to compare it with the dialog above. Correct it by hand if it differs. The file
  195. only tells the server what to write; it does not change the setting in TIA Portal. An existing file is never
  196. overwritten.
  197. Each key names an object type, the value is the text TIA Portal shows for it:
  198. | Value | Written as | Fits |
  199. | ----------------------------- | ---------------------------------------------------------- | ---------------------------------------------------- |
  200. | `SIMATIC SD(.s7dcl, .s7res)` | documents, `.s7dcl` and `.s7res` (blocks V20+, types V21+) | every block and PLC data type except STL blocks |
  201. | `.xml` | SimaticML, `.xml` | every block and PLC data type |
  202. | `.awl`, `.scl`, `.db`, `.udt` | external source, the same extension | STL, SCL, data blocks, PLC data types (not LAD, FBD) |
  203. | Key | Controls |
  204. | ------------------------------------------------------------ | -------------------------------------------------------- |
  205. | `code-blocks-LAD`, `-FBD`, `-SCL`, `-STL` | blocks of that language |
  206. | `data-blocks` | data blocks |
  207. | `plc-data-types` | PLC data types |
  208. | `safety-data-blocks-F-DBs`, `f-compliant-plc-data-types-UDT` | listed as TIA Portal shows them; not read separately yet |
  209. Rules:
  210. - Keys and values are not case sensitive. Other keys are kept and shown but have no effect, so a longer file from a
  211. copy does not break anything.
  212. - If the file has no entry for an object type that occurs in the PLC, holds a value that is not one of the formats
  213. above, or is not valid JSON, `ExportPlcProgram` fails **before it writes anything** and names the file and the key.
  214. - A LAD or FBD block that contains STL networks cannot be written as SIMATIC SD: TIA Portal refuses it with "Blocks with
  215. the programming language STL cannot be exported ... to SIMATIC SD". The server tries the format of `code-blocks-LAD` /
  216. `code-blocks-FBD` first and, when TIA Portal refuses it for that reason, uses `code-blocks-LAD-STL` (`.xml`; a file
  217. without the key behaves the same) and names the block in `Notes`. Any other value of that key makes such a block fail
  218. with a row that names the key. Other SIMATIC SD errors stay in `Failed`.
  219. - GRAPH blocks use `code-blocks-GRAPH`; a file written before that key existed exports them as `.xml`, and `tia init`
  220. adds the key. A block of any other language without an entry is skipped and listed in `Skipped`. A source format for
  221. a block that has no source form (LAD as `.awl`) is skipped with a reason.
  222. Who reads it: `ExportPlcProgram` decides the format of every object from it. `GetExportFormats(exportPath)` shows what
  223. the file says and which export tool writes each object type. `ExportBlock`, `ExportBlocks`, `ExportType` and
  224. `ExportTypes` read it too, so one tool per object kind writes every format. `ExportTagTable`, `ExportTagTables`, `ExportWatchTable`, `ExportWatchTables` and `ExportForceTable` do not,
  225. because tag, watch and force tables are always XML. `tia.json` lists `plc-tables` and `technology-objects` (`.xml`) so the file names every object type, but no tool reads them: tag tables are always XML and there is no export tool for technology objects; a file without them behaves the same. The import tools do not read it.
  226. ### Whole PLC program: `ExportPlcProgram`, `OverwritePlcProgram` and `ImportPlcProgramChanges`
  227. These tools move all blocks and PLC data types of a PLC software in one call. `ExportPlcProgram` writes each
  228. object in the format that [`tia.json`](#tiajson-the-export-formats-of-tia-portal) gives for its object type; the file
  229. is created with defaults when it is missing, so check it.
  230. SIMATIC SD documents need a project that is prepared for that format: TIA Portal refuses an object with "needs
  231. preparation for the format of Simatic SD" until you select it and run **Tools > Prepare for Simatic SD**. Openness
  232. has no call for that step, so `ExportPlcProgram` cannot do it. Such an object is listed in `Failures` with the
  233. message of TIA Portal, and the export goes on with the others; an export that finished with warnings is named in
  234. `Notes`.
  235. Blocks of a language that has no entry in the settings are skipped and listed in `Skipped`; read them with `GetXmlBlock`. `OverwritePlcProgram` and `ImportPlcProgramChanges` still import only sources and
  236. XML, so the files of a SIMATIC SD folder are not imported by them.
  237. - Layout: `<exportPath>/<softwarePath>/Program blocks/<groups>/` and `.../PLC data types/<groups>/`, one file per
  238. object, always mirroring the project groups. `ExportBlocks`, `ExportTypes` and `ExportTagTables` write slices of this
  239. tree, `ExportBlock`, `ExportType` and `ExportTagTable` single objects of it.
  240. - `ExportPlcProgram(softwarePath, exportPath)` only writes files. `OverwritePlcProgram(softwarePath,
  241. importPath, regexName, keepOnError, dryRun)` changes the project and needs `--allow-write`. Blocks and types of the same name in the open project are **replaced** by the file content.
  242. The tool description tells the agent so.
  243. - Prefer `ImportPlcProgramChanges` for edited files; use `OverwritePlcProgram` only to replace the whole tree (first
  244. import, restore, a folder without git). The name and the description of the whole-tree tool say so, so an agent does
  245. not pick it for a vague "import" request.
  246. - Both tools **preview by default** (the parameter `dryRun` is `true`): nothing is imported, and `Planned` lists every
  247. object with `create` or `overwrite` (the action is derived from the file name). The tool descriptions and
  248. prompts tell the agent to show that list to you. Exception: for a plain import request the `ImportPlcProgramChanges`
  249. prompt and description tell the agent to call it with `dryRun=false` right away, because the dialog below is the
  250. preview and the confirmation in one; it lists every file to import.
  251. - A real run (`dryRun=false`) is confirmed by **you, through the server**: it shows a confirmation dialog in the
  252. client (MCP elicitation) listing what would be imported and how many objects are overwritten, and imports only
  253. when you tick the "Yes, import" checkbox and submit. The agent cannot answer it for you, and submitting without the
  254. tick, declining or cancelling imports nothing. A
  255. client without elicitation support is refused with a message saying so; it can still run the preview.
  256. - Saving is not guarded by the server: the agent is told to call `SaveProject` (`SaveSession` in a local session)
  257. only after you say "save project", which depends on the agent following that instruction.
  258. Clients can still prompt before every call, because the tools carry `destructiveHint`.
  259. - Import puts each file into the group its folder implies; the group must already exist. An `.xml` file counts
  260. only below the `Program blocks` folder.
  261. - `ImportPlcProgramChanges(softwarePath, exportPath, regexName, keepOnError, dryRun)` takes only the files git
  262. reports as changed since the last commit below `<exportPath>/<softwarePath>/`: modified, staged and new files.
  263. Deleted files cannot be imported and are listed in `Deleted`; files with an open merge conflict go to `Ignored`.
  264. It needs git on `PATH` and an export folder inside a git repository, and takes the `--export-path` and
  265. `--software-path` presets. Suggested flow: `ExportPlcProgram`, commit the export as baseline, edit files,
  266. `ImportPlcProgramChanges` (the dialog lists the files; tick "Yes, import" and submit), `SaveProject`, commit.
  267. - Objects may need each other across the two formats (a LAD block calling an SCL block, an instance data block of
  268. a LAD function block). Import therefore works in rounds: it retries what failed as long as the last round
  269. imported something. The response reports `Rounds`, and what never succeeded in `Failures` with its last error.
  270. - To export only some objects use `ExportBlocks`, `ExportTypes` or `ExportTagTables` (optional regular expression), or
  271. `ExportBlock`, `ExportType` or `ExportTagTable` for exactly one object. There are no per-format export or import tools
  272. any more; the format is the one in `tia.json`.
  273. - `softwarePath` and `exportPath` take the presets from `--software-path` and `--export-path` like every other
  274. export.
  275. ## `tia` porcelain commands: connect, pull and push
  276. Short tools for the chat that work like the git commands they are named after. They sit on top of the tools above:
  277. `connect` attaches to TIA Portal and opens the project, `pull` brings TIA Portal into the export folder, `push`
  278. brings the changed files of that folder into TIA Portal.
  279. Type the command in the chat, e.g. `tia pull blocks ".+HMI"`, or pick the tool or the prompt of the same name.
  280. | You say | Tool | Same as |
  281. | ---------------------------- | -------------------- | --------------------------------------------------------------------------- |
  282. | `tia init` | `TiaInit` | sets up `<exportPath>/tia.json` |
  283. | `tia connect <project>` | `TiaConnect` | `OpenTiaProject` |
  284. | `tia pull` | `TiaPull` | `ExportPlcProgram` |
  285. | `tia pull blocks [rx]` | `TiaPullBlocks` | `ExportBlocks`, optionally by regex |
  286. | `tia pull types [rx]` | `TiaPullTypes` | `ExportTypes`, optionally by regex |
  287. | `tia pull tagtables [rx]` | `TiaPullTagTables` | `ExportTagTables`, optionally by regex |
  288. | `tia pull block <path>` | `TiaPullBlock` | `ExportBlock`, exactly one block by its full path |
  289. | `tia pull type <path>` | `TiaPullType` | `ExportType`, exactly one PLC data type by its full path |
  290. | `tia pull tagtable <path>` | `TiaPullTagTable` | `ExportTagTable`, exactly one tag table by its path |
  291. | `tia pull watchtables [rx]` | `TiaPullWatchTables` | `ExportWatchTables`, optionally by regex |
  292. | `tia pull watchtable <path>` | `TiaPullWatchTable` | `ExportWatchTable`, exactly one watch table by its path |
  293. | `tia pull forcetable <path>` | `TiaPullForceTable` | `ExportForceTable`, the force table of the PLC |
  294. | `tia push` | `TiaPush` | `ImportPlcProgramChanges` with `dryRun=false` |
  295. | `tia push preview` | `TiaPushPreview` | `ImportPlcProgramChanges` with `dryRun=true` |
  296. | `tia pull hardware` | `TiaPullHardware` | `ExportHardware` (device of the PLC as `Hardware/<device>.aml`) |
  297. | `tia push hardware` | `TiaPushHardware` | `ImportHardware` with `dryRun=false` (`--allow-write`, confirmation dialog) |
  298. - `TiaInit` sets up [`tia.json`](#tiajson-the-export-formats-of-tia-portal): it opens a dialog in which you check or
  299. enter the `args` (`project-path`, `software-path`, `export-path`, `keep-structure`, `with-ui`), starting with the values of the call or
  300. of the `--project-path`, `--software-path`, `--export-path` and `--keep-structure` presets (the old parameter name `preservePath` still works), and writes the file into the export path. A missing
  301. file is created with the export formats TIA Portal offers for a new workspace; an existing file is only completed
  302. (missing keys are added) and never overwritten, so a value you wrote is kept. Cancel the dialog and nothing is
  303. written. A client without dialogs uses the arguments and presets as they are. It does not touch the project and needs
  304. no `--allow-write`. Check the export formats against the dialog of TIA Portal afterwards.
  305. - `TiaConnect` connects to the running TIA Portal (or starts one), opens the `.apXX` project or `.alsXX` session
  306. and returns the PLC software paths to use as `softwarePath`. `path` takes the preset of `--project-path`; pass
  307. `portalId` when several instances run. It closes the project that is open first, unless it is the one asked for.
  308. - The pull tools write the tree of `ExportPlcProgram`, each object in the format of `<exportPath>/tia.json`, so a pull
  309. of blocks and a pull of the whole program land in the same folders. `TiaPullTagTables` writes one XML file per tag
  310. table below `<exportPath>/<softwarePath>/PLC tags/<groups>/`, `TiaPullWatchTables` one per watch table below the watch and force tables folder; both have one format only.
  311. - The optional regular expression (`regexName`) selects objects by name, e.g. `.+HMI`. `TiaPullBlocks` writes no
  312. types and `TiaPullTypes` no blocks.
  313. - The push tools are the import tools under another name and need `--allow-write`. `TiaPush` shows the same
  314. confirmation dialog ("Yes, import") and `TiaPushPreview` imports nothing. They read only the files git reports as
  315. changed, and not the tag or watch tables; there is no tool that imports tag tables.
  316. - `softwarePath` and `exportPath` take the presets from `--software-path` and `--export-path`.
  317. ## Example Prompts using natural language
  318. Example prompts using natural language with preset parameters in json config file.
  319. ```json
  320. {
  321. "servers": {
  322. "tia-mcp-server": {
  323. "type": "stdio",
  324. "command": "E:\\Labor\\GitHub\\tiaportal-mcp\\src\\TiaMcpServer\\bin\\Debug\\net48\\TiaMcpServer.exe",
  325. "args": [
  326. "--tia-major-version", "21",
  327. "--project-path", "<path-to-project>\\<project-name>.(ap21|als21)",
  328. "--software-path", "<software-path>",
  329. "--export-path", "${workspaceFolder}\\export",
  330. "--allow-write"
  331. ],
  332. "env": {}
  333. }
  334. }
  335. }
  336. ```
  337. Prompts:
  338. - 'open tia project'
  339. - 'export all types to sources'
  340. - 'export all blocks as sources'
  341. - 'export blocks as sources, which match regex name pattern ".+HMI_.+"'
  342. - 'export all tags'
  343. - 'import modified type sources'
  344. - 'get project tree and save output to project-tree.txt'
  345. - 'get software tree and save output to software-tree.txt'
  346. - 'export watch tables'
  347. - 'export force tables'
  348. - 'export opc ua'
  349. - 'save project'
  350. - 'compile project'
  351. - 'close project'
  352. - 'show doctor diagnostics for tia'
  353. Prompts using the `tia` commands (see "`tia` porcelain commands" above; with the presets from the json config
  354. file `softwarePath` and `exportPath` can be left out):
  355. - 'tia init'
  356. - 'tia connect'
  357. - 'tia pull'
  358. - 'tia pull blocks'
  359. - 'tia pull blocks ".+HMI_.+"'
  360. - 'tia pull types'
  361. - 'tia pull tagtables'
  362. - 'tia pull watchtables'
  363. - 'tia pull block Group1/Subgroup/FB_Motor'
  364. - 'tia pull type Group1/Udt_Drive'
  365. - 'tia pull tagtable TagGroup1/Table1'
  366. - 'tia pull watchtable WatchGroup1/WatchTable_1'
  367. - 'tia pull forcetable ForceTable'
  368. - 'tia push preview'
  369. - 'tia push'
  370. - 'save project'
  371. ## Prompts using slash commands
  372. Every tool has a prompt of the same name that you can start as a slash command, for example
  373. `/mcp__tia-mcp-server__OpenProject D:\Siemens\Test\TestProject1_V21.ap21`. The part after `mcp__` is
  374. the server name from your MCP configuration. Claude Code shows the prompt description and the
  375. argument names, matches the typed values to the arguments by position and requires every argument
  376. without a default. A prompt only sends text to the model, which then calls the tool.
  377. A value with spaces goes in **double quotes**, for example a PC based PLC software or an export
  378. folder:
  379. ```
  380. /mcp__tia-mcp-server__ExportBlocks "PC-System_1/Software PLC_1" "D:\My Export"
  381. ```
  382. Claude Code itself splits the text at every space and drops the words beyond the last argument. The
  383. server joins the pieces of a quoted value again, so the value reaches the tool unchanged; `""`
  384. passes an empty value. All typed words together must not exceed the number of arguments of the
  385. prompt, so a prompt with few arguments (for example `GetSoftwareInfo`, which only has
  386. `softwarePath`) cannot take a value of several words: write a normal request instead of the slash
  387. command.
  388. ## Requirements
  389. - __.net Framework 4.8__ installed
  390. - __Siemens TIA Portal V21__ installed and running on your machine
  391. - Check if under `Environment Variables/User variable for user <name>` the variable `TiaPortalLocation` is set to `C:\Program Files\Siemens\Automation\Portal V21`
  392. - User must be in Windows User Group `Siemens TIA Openness`
  393. ### Diagnose the environment
  394. Run the server with `--doctor` to check all of the above without starting the MCP server:
  395. ```text
  396. > TiaMcpServer.exe --doctor
  397. Diagnose:
  398. ├─ Connected = False
  399. ├─ Project: No project open
  400. ├─ Active Version: V21
  401. ├─ Installed TIA Portal versions:
  402. │ └─ V21: C:\Program Files\Siemens\Automation\Portal V21
  403. │ ├─ Engineering: OK
  404. │ └─ Portal: OK
  405. ├─ User in 'Siemens TIA Openness' user group: True
  406. └─ Write mode (--allow-write): disabled, read-only tools only
  407. ```
  408. The report ends with the command line options and their values. The deprecated `--preserve-path` is listed as
  409. `--preserve-path (deprecated, use --keep-structure) = used` when a configuration still passes it (otherwise `not used`),
  410. so you know which configurations to update.
  411. The same report is available to MCP clients through the `Doctor` tool, which additionally returns
  412. the findings as structured content. Both are read-only: they never connect to TIA Portal, open a
  413. project, or change user group membership.
  414. ## TIA-Portal Versions
  415. - __V21__ is the default version.
  416. - Previous versions are also supported, but must use the `--tia-major-version` argument to specify the version.
  417. - SIMATIC SD documents (.s7dcl/.s7res), the format `tia.json` selects for an object type, need TIA Portal V20 or
  418. newer for blocks (`ExportBlock`, `ExportBlocks`, `ExportPlcProgram`).
  419. - The same for PLC data types - `ExportType`, `ExportTypes` - requires TIA Portal **V21** or newer:
  420. Openness only added `PlcType.ExportAsDocuments` and `PlcTypeComposition.ImportFromDocuments`
  421. in V21.
  422. ## SIMATIC Source Documents
  423. A source document is the readable, git-diffable form of an object: `<Name>.s7dcl` holds the
  424. declaration and body as SCL/LAD/STL text, the optional `<Name>.s7res` holds comments and
  425. language resources. Every other export in this server writes SimaticML XML instead, which
  426. diffs poorly.
  427. The file names come from TIA Portal, not from this server: an export response lists the files
  428. that were actually written, and a batch import discovers a document set by base name rather
  429. than assuming one extension. Tag tables and watch tables have no document API in Openness V21
  430. and remain XML-only.
  431. The export mirrors the project tree below the system folder - `Program
  432. blocks` for blocks, `PLC data types` for types - using the folder name as TIA Portal reports it
  433. in the current interface language. `OverwritePlcProgram` and `ImportPlcProgramChanges` read
  434. that tree back, so an export can be fed straight back in.
  435. A PLC data type name is unique across the whole PLC, not just within its group. Importing a
  436. name that already exists into a *different* group therefore fails with "an object with the name
  437. ... already exists in the plc", even with `importOption: Override`; point `groupPath` at the
  438. group the type already lives in to replace it.
  439. ## Known Limitations
  440. - As of 2025-09-02: Importing Ladder (LAD) blocks from SIMATIC SD documents requires the companion `.s7res` file to contain en-US tags for all items; otherwise import may fail. This is a known limitation/bug in TIA Portal Openness.
  441. - `ExportBlock` requires a fully qualified `blockPath` like `Group/Subgroup/Name`. If only a name is provided, the tool fails with "Block not found"; use `GetBlocks` to find the path.
  442. ### Limits imposed by the Openness API itself
  443. These are not gaps in this server - the underlying API offers no operation for them.
  444. - __No move or copy for blocks and types.__ `CopyBlock`, `MoveBlock`, `CopyType` and `MoveType`
  445. are composed from export, import and (for a move) deleting the source once the import
  446. succeeds. Two consequences are visible: the object must be consistent, because TIA Portal
  447. refuses to export an inconsistent one, and its block number travels with it, so importing
  448. into the same PLC can hit a number collision. Renaming during a copy is not offered - it
  449. would mean rewriting the exported XML.
  450. - __No generic "create block".__ Only `CreateFB` and `CreateInstanceDB` exist; every other kind
  451. of block has to arrive through `OverwritePlcProgram` or `ImportPlcProgramChanges`.
  452. - __Read-only objects.__ System constants cannot be created or changed, the force table cannot
  453. be created or deleted (the system owns one per PLC), the default tag table cannot be deleted,
  454. and the system groups (`Program blocks`, `PLC data types`, `PLC tags`, ...) cannot be renamed
  455. or deleted. These all fail with a `NotSupported` message rather than an opaque Openness error.
  456. - __No cross references__ for watch tables, force tables or external sources; `GetCrossReferences`
  457. reports `NotSupported` for them.
  458. - __Watch table entries__ cannot be created or deleted through this server yet. The Openness
  459. composition holding them exposes only a comment-row creator, so adding a real entry needs an
  460. untyped creation call whose required attribute names must first be read from the live API.
  461. - __Safety programs.__ F-blocks and safety tags reject most edits, sometimes requiring the safety
  462. password. The server does not pre-guess Siemens' rules: the underlying error is passed through
  463. with its original message.
  464. - __Know-how protected__ blocks and types are rejected before any edit, with a message asking you
  465. to remove the protection in TIA Portal first.
  466. ## Testing
  467. - See `tests/TiaMcpServer.Test/README.md` for environment prerequisites and test asset setup.
  468. - Standard command: `dotnet test` (run from the repo root).
  469. - Test execution policy: offer to run tests, but only execute after explicit user confirmation. Details in `AGENTS.md`.
  470. ## Contributing
  471. - See `agents.md` for guidance on working with agentic assistants and the test execution policy (offer to run tests only with explicit user confirmation).
  472. ## Error Handling
  473. - The Portal layer throws `PortalException` with a short message and `PortalErrorCode`
  474. (`NotFound`, `InvalidParams`, `InvalidState`, `ExportFailed`, `ImportFailed`, `CreateFailed`,
  475. `DeleteFailed`, `RenameFailed`, `NotSupported`, `WriteDisabled`), and attaches `softwarePath`, `blockPath`, `exportPath` in `Exception.Data` while preserving `InnerException` on export failures.
  476. - The MCP layer rethrows these as `McpException`. Since SDK 2.x, an `McpException` thrown from a tool is returned to the client as a `CallToolResult` with `isError: true` and the message as text content, rather than as a JSON-RPC error, so the model can read the reason and self-correct. For `ExportFailed` the message includes a concise reason from the underlying error; for `NotFound` it may suggest likely full block paths if a bare name was provided.
  477. - Consistency required: TIA Portal never exports inconsistent blocks/types. Single export returns `InvalidParams` with a message to compile first. Bulk export skips inconsistent items and returns them in an `Inconsistent` list alongside `Items`.
  478. - Standardization: Exception context metadata is attached in a single catch per portal method right before rethrow, not at inline throw sites. See `docs/error-model.md`.
  479. - Since 0.2.0 this is implemented once, in the `Operation.Run` helper, which every portal method
  480. added for tags, watch tables, external sources, cross references and the write operations
  481. routes through. The older export/import methods still carry their hand-written equivalent of
  482. the same block; migrating them is tracked in `TODO.md`.
  483. - `Operation.Run` also serializes all Openness calls behind a lock. Openness objects are not
  484. thread-safe and the MCP SDK may dispatch tool calls concurrently; with write tools enabled an
  485. unsynchronized race could corrupt project state rather than merely return stale data.
  486. ## MCP Protocol
  487. - Built on the [ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol) .NET SDK **2.2.0**.
  488. - Protocol revisions negotiated during `initialize`: `2024-11-05`, `2025-03-26`, `2025-06-18`, `2025-11-25` (the SDK picks the highest the client also supports).
  489. - Every tool advertises a human-readable `title` and behaviour annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
  490. - 27 read tools and all 37 write tools publish an `outputSchema` and return `structuredContent`.
  491. - Long-running export/import tools report progress via `notifications/progress` when the client supplies a `progressToken`.
  492. - Tool failures are returned as tool results with `isError: true` (not JSON-RPC errors), so the model can read the message and retry.
  493. - Pull, push, hardware and compile tools return a `Report`: the complete result as markdown tables (counts, every skipped object, every failure, every message). The server instructions ask the client to show it to the user verbatim instead of summarizing it.
  494. ## Transports
  495. - Supported today: `stdio`
  496. - Program wires `AddMcpServer().WithStdioServerTransport()`.
  497. - For stdio, logs must go to stderr to avoid corrupting JSON-RPC.
  498. - Available via SDK: `stream` (custom streams)
  499. - The SDK exposes `WithStreamServerTransport(Stream input, Stream output)` which can be used to host over TCP sockets or other streams.
  500. - Not wired in this repo yet.
  501. - HTTP/Streamable HTTP: not implemented yet
  502. - `ModelContextProtocol` 2.2.0 ships its Streamable HTTP server transport in `ModelContextProtocol.AspNetCore`, which targets .NET 8+.
  503. - This server targets `net48` (required by TIA Openness), so Streamable HTTP cannot be hosted from this process.
  504. - A separate .NET 8+ proxy process would be required to expose this server over HTTP.
  505. ## Client configuration
  506. The server runs locally over `stdio`, so every client starts `TiaMcpServer.exe` itself. Use the
  507. absolute path of the executable (`<path-to>` below) and double the backslashes in JSON. All
  508. arguments from [Command Line Arguments](#command-line-arguments) go into `args`; the presets
  509. (`--project-path`, `--software-path`, `--export-path`, ...) and `--allow-write` are optional.
  510. ### GitHub Copilot (VS Code)
  511. - Workspace file `.vscode/mcp.json` (or `MCP: Open User Configuration` for all workspaces). The
  512. root key is `servers`. Example with the VS Code extension
  513. [TIA-Portal MCP-Server](https://marketplace.visualstudio.com/items?itemName=JHeilingbrunner.vscode-tiaportal-mcp)
  514. and TIA-Portal V21:
  515. ```json
  516. {
  517. "servers": {
  518. "tia-mcp-server": {
  519. "type": "stdio",
  520. "command": "c:\\Users\\<user>\\.vscode\\extensions\\jheilingbrunner.vscode-tiaportal-mcp-<version>\\srv\\net48\\TiaMcpServer.exe",
  521. "args": [
  522. "--tia-major-version", "21",
  523. "--project-path", "D:\\Projects\\Plant\\Plant.ap21",
  524. "--software-path", "PLC_1",
  525. "--export-path", "${workspaceFolder}\\export",
  526. "--allow-write"
  527. ],
  528. "env": {}
  529. }
  530. }
  531. }
  532. ```
  533. Then switch Copilot Chat to *Agent* mode and enable the server's tools in the tools picker.
  534. ### Claude Code
  535. - Project scope, file `.mcp.json` in the repository root (checked in, shared with the team). The
  536. root key is `mcpServers`:
  537. ```json
  538. {
  539. "mcpServers": {
  540. "tia-mcp-server": {
  541. "type": "stdio",
  542. "command": "<path-to>\\TiaMcpServer.exe",
  543. "args": [
  544. "--tia-major-version", "21",
  545. "--project-path", "D:\\Projects\\Plant\\Plant.ap21",
  546. "--software-path", "PLC_1",
  547. "--export-path", "${CLAUDE_PROJECT_DIR}\\export",
  548. "--allow-write"
  549. ],
  550. "env": {}
  551. }
  552. }
  553. }
  554. ```
  555. `${CLAUDE_PROJECT_DIR}` is expanded by Claude Code to the project root; use an absolute path if
  556. your Claude Code version does not.
  557. - The same from the command line (`--scope user` for all projects, `--scope project` writes
  558. `.mcp.json`, `--scope local` is the default and private). Everything after `--` is the command:
  559. ```powershell
  560. claude mcp add tia-mcp-server --scope project -- "<path-to>\TiaMcpServer.exe" --tia-major-version 21 --project-path "D:\Projects\Plant\Plant.ap21" --software-path PLC_1 --export-path "D:\Export" --keep-structure --with-dependencies
  561. ```
  562. Check it with `claude mcp list` or `/mcp` inside Claude Code.
  563. ### Gemini CLI
  564. - `~/.gemini/settings.json` (user) or `.gemini/settings.json` in the project (project scope). The
  565. root key is `mcpServers`:
  566. ```json
  567. {
  568. "mcpServers": {
  569. "tia-mcp-server": {
  570. "command": "<path-to>\\TiaMcpServer.exe",
  571. "args": [
  572. "--tia-major-version", "21",
  573. "--project-path", "D:\\Projects\\Plant\\Plant.ap21",
  574. "--software-path", "PLC_1",
  575. "--export-path", "D:\\Export"
  576. ],
  577. "env": {},
  578. "timeout": 120000
  579. }
  580. }
  581. }
  582. ```
  583. `timeout` is in milliseconds; raise it for long exports or compiles. Check it with `/mcp` inside
  584. Gemini CLI. Do not set `"trust": true` together with `--allow-write`, because that skips the
  585. confirmation prompt for the project-changing tools.
  586. ### Claude Desktop
  587. - Create/Edit to add/remove server to `C:\Users\<user>\AppData\Roaming\Claude\claude_desktop_config.json`:
  588. ```json
  589. {
  590. "mcpServers": {
  591. "vscode-tiaportal-mcp": {
  592. "command": "<path-to>\\TiaMcpServer.exe",
  593. "args": [],
  594. "env": {}
  595. }
  596. }
  597. }
  598. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.