Skip to content
Back to search

tia-portal-mcp

Specialized bridge designed to connect LLMs and AI agents directly to Siemens SIMATIC TIA Portal V21.

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/Czarnak/tia-portal-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/Czarnak/tia-portal-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/czarnak--tia-portal-mcp/badge.svg)](/listings/czarnak--tia-portal-mcp)

HTML

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

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the server as a .NET global tool, check your environment, and register it with an MCP client:

dotnet tool install -g TiaMcpServer
tia-mcp doctor
tia-mcp install claude-code

`tia-mcp doctor` validates Windows version, .NET runtimes, the TIA Portal installation, Openness assemblies, user-group membership, and host/worker compatibility before you connect anything. Run it first — it reports exactly which prerequisite is missing.

| Prerequisite | Notes | | --- | --- | | Windows | Windows-only; the Openness API has no other host | | Siemens TIA Portal V21 | with Openness installed and enabled | | `Siemens TIA Openness` group | the current Windows user must be a member | | Framework-dependent global tool: stable .NET 10 SDK 10.0.400 or newer | provides `dotnet tool install` and the supported .NET 10 runtime | | .NET Framework 4.8 runtime | required by the Openness worker process |

The framework-dependent `tia-mcp` global tool requires a supported .NET 10 runtime. The separate self-contained `win-x64` archive includes the host runtime. Neither installation method requires users to install the `ModelContextProtocol` NuGet package.

Custom .NET integrations that compile directly against the C# MCP SDK must review the ModelContextProtocol 2.2 migration notes and retest protocol negotiation, tool schemas, and structured results. This custom-integration requirement is separate from the `browse_project_tree` v3 migration described above.

Supported clients for `tia-mcp install`: Claude Code, Codex, OpenCode, MiMoCode. Servers register in **read-only** mode by default (six tools); add `--access-mode read-write` for edits, compilation, and lifecycle with one prompt per actual call (sixteen tools). Select `--access-mode full` for lifecycle without server elicitation and PLC runtime control (sixteen tools).

Binding to a specific project, every install option, and the full access-mode reference are in the [installation guide](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/guides/installation.md). To build from source instead of installing the published tool, see [building from source](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/development/building.md).

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 · 251 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. [![Build Status](https://img.shields.io/github/actions/workflow/status/Czarnak/tia-portal-mcp/ci.yml?branch=main&style=flat-square)](https://github.com/Czarnak/tia-portal-mcp/actions)
  3. [![Codecov](https://img.shields.io/codecov/c/github/Czarnak/tia-portal-mcp?style=flat-square)](https://codecov.io/gh/Czarnak/tia-portal-mcp)
  4. [![GitHub Release](https://img.shields.io/github/v/release/Czarnak/tia-portal-mcp?style=flat-square)](https://github.com/Czarnak/tia-portal-mcp/releases)
  5. [![.NET SDK](https://img.shields.io/badge/.NET-10.0-512BD4.svg?style=flat-square&logo=dotnet)](https://dotnet.microsoft.com/)
  6. [![.NET Framework](https://img.shields.io/badge/.NET_Framework-4.8-512BD4.svg?style=flat-square&logo=dotnet)](https://dotnet.microsoft.com/)
  7. [![TIA Portal](https://img.shields.io/badge/TIA_Portal-V21-009999.svg?style=flat-square&logo=siemens)](https://new.siemens.com/global/en/products/automation/industry-software/automation-software/tia-portal.html)
  8. [![MCP](https://img.shields.io/badge/MCP-Ready-000000.svg?style=flat-square)](https://modelcontextprotocol.io/)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://github.com/Czarnak/tia-portal-mcp/blob/main/LICENSE)
  10. ![NuGet Downloads](https://img.shields.io/nuget/dt/TiaMcpServer)
  11. MCP server for Siemens SIMATIC TIA Portal V21. It lets MCP clients and AI agents inspect a running TIA Portal project through the Siemens Openness API.
  12. The current implementation covers project discovery and lifecycle operations, PLC block export/import, tag table reads, guarded PLC software writes, hardware/network discovery, WinCC Unified HMI inspection and guarded tag-table/tag/alarm writes, standalone VCI workspace operations, library inspection and guarded library writes, cross-reference diagnostics, hardware catalog search, guarded network-device provisioning, and compile/check diagnostics.
  13. ## Tools
  14. The server exposes 9 tools in `read-only` (the startup default), 21 in `read-write`, and the same 21 in `full`.
  15. `read-write` permits in-project edits, compilation and project lifecycle calls, asking once per actual lifecycle call.
  16. `full` adds no tools or operations; it only runs lifecycle calls without the prompt. Every write tool
  17. (`plc_write`, `network_write`, `hmi_write`, `vci_write`, `library_write` and the six lifecycle tools) uses one guarded single-call pipeline; there are no
  18. safety tokens and no PLC run/stop.
  19. ### PLC reads and cross-references
  20. - `plc_read` - run up to 50 PLC read operations in one call: `get_block_content`, `get_type_content` and `list_tag_tables`. Each item carries a unique `operationId`, an `operation` name, and that operation's parameters. Items run independently, so a failing item does not stop the others. Results are structured JSON with `contractVersion` `1.0`; a value over the value budget (60,000 characters by default) is omitted whole with narrowing guidance, never cut.
  21. - `read_cross_references` - read the cross-references of one project-tree target (a block, type, tag, constant, or a PLC, software unit or folder swept over every owner beneath it). Arguments: `target`, `filter`, `maxResults`. Both reads are available in every access mode and act on the bound project only; they never open or switch a project, and without a verified binding they fail closed with `binding_conflict` (call `bind_project` first).
  22. ### HMI reads and writes
  23. - `hmi_read` - run up to 50 read-only WinCC Unified HMI operations in one call (devices, tags, connections, alarms, logs, screens and items, faceplates, navigation, runtime settings, script modules, text and graphic lists, languages and `validate`). Registered in every access mode, paged with `offset`/`limit` (default 100), structured JSON with `contractVersion` `1.1`. Classic WinCC devices are listed but not read. See the [HMI operations summary](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/HMI_OPERATIONS_SUMMARY.md).
  24. - `hmi_write(operations, dryRun=false)` - create, update or delete WinCC Unified tag tables, tags and discrete/analog alarms: nine operations in read-write/full, up to 50 caller-ordered items on one verified standalone project or local session, with write contract `2.0`. Set `dryRun:true` for preview; execution stops at the first failure without batch rollback or server elicitation. `EngineeringTargetInvocationException` during mutation is `engineering_rejected` unless `portal_lost` takes precedence. Typed Siemens failures carry `engineeringError` except for `portal_lost`; partial outcomes are conditional on writer allocation. Inspect actual state, run public `validate` and compile the HMI device in TIA Portal after writes. The [HMI reference](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/HMI_OPERATIONS_SUMMARY.md#writes-hmi_write) documents fields, three guards and shared verification; the [qualification record](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/superpowers/acceptance/reports/2026-10-30-hmi-write-native-rejections-live-verification.md) records completed qualification within the recorded R1/R2/R3 scope.
  25. ### Version Control Interface
  26. - `vci_read` - inspect standalone-project workspaces, paged mappings, optional raw status and supported leaf formats in every mode.
  27. - `vci_write(operations, dryRun=false)` - create/delete workspaces, export leaf scopes, sync in either direction and delete mappings in read-write/full. It executes by default, previews with `dryRun:true`, and stops after the first failed item without rollback across items or server elicitation. Save the project to persist workspaces and mappings; inspect current state before retrying. The [VCI reference](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/VCI_OPERATIONS_SUMMARY.md) gives formats, path guards, sync decisions, Portal-loss recovery and scoped acceptance limits.
  28. ### Library reads
  29. - `library_read` - run up to 50 read-only library operations in one call: `list_global_libraries`, `inspect_library`, `list_children`, `list_versions` and `list_dependencies`. Registered in every access mode, structured JSON with `contractVersion` `1.0`. It needs a verified binding like every content tool (`bind_project` first) and never opens, retrieves, saves, closes or changes a library. `list_global_libraries` lists every global library available in the bound Portal (system, corporate and user) with `libraryType` and `isOpen`; only libraries already open in TIA Portal can be read further. Project-library reads work on standalone projects. Paged operations take `offset`/`limit` (1-200, default 100) or the returned `nextCursor`, which continues a frozen row set with live values. A flag that cannot be read is null with a diagnostic, never false. See the [library operations summary](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/LIBRARY_OPERATIONS_SUMMARY.md) for fields, paging and the live-verified scope.
  30. ### Library writes
  31. Global `inspect_library` can include author, multilingual comments, languages, history and product
  32. metadata with `includeMetadata:true`. `create_global` returns metadata and accepts an optional
  33. nonblank author, capped at 255 UTF-16 code units; release authors share that cap. `set_comments` edits
  34. multilingual comments and `set_languages` activates languages or sets editing/reference languages on an
  35. already-open global library. Each metadata item uses a native transaction and checks its end-state
  36. before commit; edits dirty the library without saving it. Last writer wins; inspect metadata before retrying
  37. an uncertain commit/disposal failure. Language removal is not supported.
  38. - `library_write(operations, dryRun=false)` - 22 operations in read-write/full, up to 50 caller-ordered items, write contract `2.0` (`library_read` stays `1.0`): global-library lifecycle, folders, master copies and versioned FB/FC/PLC UDT types (`create_type`, `create_type_version`, `release_type_version`, `set_default_type_version`, `synchronize_type`, `instantiate_type_version`, `delete_type`, `delete_type_version`). Every call needs a verified binding; project-library and PLC items need a standalone project. It executes by default, previews with `dryRun:true`, stops at the first failure and never rolls back the batch. Read-write asks once only for a call containing global-library lifecycle; content-only calls and full never ask. Only previews and prompting calls plan. Other applies return `effects:[]`, resolve items as they run and can use earlier creations. Change type content through a fresh `plc_read` hash, `create_type_version` and release; a compile-first workflow is recommended for library-placed PLC objects before content reads. Release and synchronization report default changes without restoring the previous default. See the [library operations summary](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/LIBRARY_OPERATIONS_SUMMARY.md#writes-library_write) for selectors, checks, planned-call dependencies and live scope.
  39. ### PLC writes
  40. - `plc_write(operations, dryRun=false)` - run up to 50 PLC software writes in caller order against one verified, already-open project. Operations: `update_block_logic`, `update_type_content`, `create_block` / `delete_block`, `create_block_group` / `delete_block_group`, `create_tag_table` / `delete_tag_table`, `create_tag` / `update_tag` / `delete_tag`, `create_user_constant` / `update_user_constant` / `delete_user_constant`. Set `dryRun:true` to preview effects and guards without mutation. No confirmation prompt is sent in any mode. Phases are `preview`, `applied`, `blocked` and `error`. Execution stops at the first failure and never rolls back, so re-read with `plc_read` before retrying. Later items may use objects created earlier in the same call. Creates are not collision-checked before mutation. Scoped live cases demonstrated duplicate tag, table, block and group rejections, the default-table delete rejection, and four additional namespace directions; this is not a guarantee for every collision. Native `EngineeringTargetInvocationException` failures in mutation worker methods become `engineering_rejected` with the exception type, bounded message and inner chain in `engineeringError` (Portal UI language). Guards cover delete consequences, address overlap and unreadable evidence; the singleton-OB check is retained because native redundancy was not demonstrated. Verification reads back content only (`contentHash`), `trusted` otherwise (write contract `2.0`); see the [PLC operations reference](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/PLC_OPERATIONS_SUMMARY.md#failures-from-tia-portal).
  41. Content writes (`update_block_logic`, `update_type_content`) take the document as `content` together with `expectedContentHash`, the `contentHash` from a `plc_read` of the same object in the same format. Content changed since that read is rejected with `state_changed`. A document over the value budget is omitted from the read, has no hash, and cannot be updated through `plc_write`; the budgets default to 60,000 characters per value and 180,000 per response and can be raised at startup with `--max-item-chars`/`--max-document-chars` (see [response size limits](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/guides/mcp-client-configuration.md#response-size-limits)). `preview_write_batch`, `apply_write_batch` and `execute_read_batch` were retired; their operations moved to `plc_write` and `plc_read`.
  42. Every operation result may carry a `warnings` array — non-fatal degradation notes captured from the TIA Openness worker. A populated `warnings` array means the payload may be partial.
  43. Available `plc_read` operations: `get_block_content`, `get_type_content`, and `list_tag_tables`.
  44. `get_block_content` / `update_block_logic` and `get_type_content` / `update_type_content` accept a `format` field. `format=source` is available for global data blocks, PLC data types, and SCL-language FB/FC/OB. Every other block language stays on `format=xml`.
  45. `withDependencies` (`plc_read` only, default `false`) asks TIA Portal to include the object's dependency closure. The resulting document declares several objects and is **context only** — a write refuses any source declaring more than one object, and the read carries a warning saying so. Omit the field to get a document you can edit and submit back.
  46. `get_block_content` and `get_type_content` reads also return a `contentHash` (`xml:sha256:<hex>` or `source:sha256:<hex>`) computed over the exact text served in `result`, tagged with the served format. It lets a later guarded write detect that the document changed since it was read. It is omitted for `withDependencies` reads, failed reads, and results truncated or omitted for size.
  47. ### Network operations
  48. `network_read` and `network_write` both declare an MCP output schema and return one canonical JSON document identically as the `content` text block and as `structuredContent` — never a nested JSON string inside an outer envelope. Both use contract version `1.0`, root warnings arrays and explicit nulls; see [docs/SupportedOperations/NETWORK_OPERATIONS_SUMMARY.md](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/NETWORK_OPERATIONS_SUMMARY.md) for the exact envelopes.
  49. - `network_read` - run up to 50 dedicated network reads: `read_hardware_config`, `search_equipment_catalog`, `list_network_objects`, and `inspect_network_object`. Reads run independently. Bound catalog searches with `query` and `maxResults`; `read_hardware_config` accepts an optional `deviceName` filter, an optional `plcName` for tag matching, and opt-in structured I/O extraction (`includeIoDetails` for addresses and channels, `includeTagMatches` for exact PLC tag matches per channel). Detailed I/O output can be large, so filter by `deviceName` or split into separate calls.
  50. - `network_write` - preview or apply up to 50 dedicated network writes: `add_network_device` (flat `typeIdentifier`/`deviceName`, since it names something that does not exist yet), `configure_network_device` (nested `target: { deviceName, nodeId }` plus `changes: { ipAddress?, subnetMask?, pnDeviceNameAutoGeneration?, pnDeviceName?, subnet?: { subnetId }, ioSystem?: { subnetId, number } }` — a null `changes` member means leave that setting unchanged), `create_subnet` (`subnet: { name, networkType }`, plus PROFIBUS-only `highestAddress`/`transmissionSpeed`), `update_subnet` (`target: { kind: "subnet", subnetId }` plus `subnetChanges` with at least one member), and `delete_subnet` (`target: { kind: "subnet", subnetId }` — connected or not). Set `dryRun:true` to preview. `dryRun:false` or omitting `dryRun` executes, with no server Network elicitation in read-write/full. Legacy `confirm`, `acknowledge`, unknown roots and nonboolean `dryRun` are rejected before tool entry. Writes require a verified binding to the exact already-open project. Apply is sequential, stops on the first failure, marks later items skipped, and does not roll back completed writes: `network_write` attaches an explicit warning to the failed item that this operation and any earlier operation in the same call may already have changed TIA state, and that you should re-read with `network_read` before retrying rather than blindly re-running the batch.
  51. `configure_network_device` selects one exact device/node and exact subnet/IO tuple, with no first-match fallback. Applied settings receive immediate and final effective-prefix checks; unreadable evidence cannot pass. Requested skips fail the item while retaining sparse typed results. Connected subnet deletion is informational; incomplete consequence inventory blocks every mode. Results use `phase:applied` even when execution or verification fails (`error:null`, MCP `isError:false`). Inspect current state before retrying; output omission may report delivery `success:false` while actual execution summaries remain successful. See the [Network contract](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/NETWORK_OPERATIONS_SUMMARY.md#network_write-envelope) for guards, sparse results, and whole-value omission recovery.
  52. `read_hardware_config` additionally reports unreadable members in a payload-level `messages` array; device/module name and type-identifier fields omit values that could not be read instead of returning `0`/empty-string placeholders (a few secondary name fields still fall back to an empty string, with the failure noted in `messages`). Hardware configuration data is engineering evidence, not certification that a physical installation has been commissioned.
  53. `read_hardware_config` supports opt-in structured I/O extraction. With `includeIoDetails: true`, each device item carries an `ioDetails` object with `addresses[]` (Openness `Address` evidence: `ioType`, byte-based `startAddress`, `length`, dynamic `context`, and ordinal `controllerNames`) and `channels[]` (`number`, `ioType`, `type`, bit-based `channelAddressBits`, `channelWidthBits`, and a formatted `logicalAddress` such as `%I4.0`/`%IW64` emitted only when the evidence is present and aligned). With `includeTagMatches: true` (which requires `includeIoDetails`), each channel carries `tagMatches[]` resolved deterministically against one selected PLC's tag tables — `plcName` selects the PLC by exact name, otherwise tag matching applies only when exactly one PLC exists. A tag matches a channel only when its normalized absolute I/O interval is identical to the channel's, and tags are never matched across controllers. A default read (no flags) returns no `ioDetails`; the current envelope and additive evidence follow the declared Network contract. See [docs/SupportedOperations/NETWORK_OPERATIONS_SUMMARY.md](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/NETWORK_OPERATIONS_SUMMARY.md) for the exact request/response shapes and unit semantics.
  54. Large hardware reads can opt into cursor pagination with `pageSize` (`1..200`) or `cursor`. Pages count devices first and then subnets in one stable sequence while keeping the two public arrays separate; canonical size projection may return fewer complete entities than requested. Follow `pagination.nextCursor` until it is absent/null and keep the project, filters, and detail flags unchanged. Requests with neither field use the unpaged path under the current declared contract. Cursors are process-local and cannot survive a host restart. See the [Network operations reference](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/NETWORK_OPERATIONS_SUMMARY.md#hardware-configuration-pagination) for recovery and omission semantics.
  55. ### Project tools
  56. - `bind_project` — default `bind` adopts an already-open project in any mode; omit the path to adopt the sole open project or list candidates. Use `forceRebind:true` to switch. Explicit `list_portals` discovers without adoption; five Project Server inventory actions inspect the persistent attached instance without changing project binding. Reattachment may show TIA's human-answerable Openness access dialog. See [Multiuser inventory and acceptance limits](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/MULTIUSER_OPERATIONS_SUMMARY.md).
  57. - `get_project_status` — inspect active project metadata without opening, binding, or switching projects; it takes no arguments.
  58. - `browse_project_tree` — browse a canonical, paged v3 point-in-time project-tree snapshot with optional typed PLC block header author, version, family, and header-name metadata in block-node `details` (default-on string fields: `HeaderAuthor`, `HeaderVersion`, `HeaderFamily`, and `HeaderName`), typed `startSelector`, `depth`, and `pageSize`; continue with the returned opaque `cursor`.
  59. - `compile_check` — compile a PLC or selected block and return compiler messages; available in read-write and full modes.
  60. - `open_project` / `create_project` / `save_project` / `save_project_as` / `archive_project` / `close_project` - guarded single-call lifecycle writes in read-write and full. Read-write asks once per actual call; full proceeds without server elicitation. Set `dryRun:true` to inspect effects and guards without mutation or elicitation. These tools advertise structured outputs and accept no public confirmation list or safety token; they remain single-tool only.
  61. Local sessions use the observed typed `.amc21` path for adoption, basic status and already-open
  62. startup assertions; writable `open_project` accepts an exact existing `.als21` file. Content reads
  63. (`browse_project_tree`, `plc_read`, `network_read`, `read_cross_references`, `hmi_read`) work on a
  64. bound local session, and so do `plc_write`, `network_write`, `hmi_write`, `compile_check` and `save_project`.
  65. A local `save_project` saves the session through `LocalSession.Save()` and never checks in to the
  66. Project Server; create, save-as, archive, close and other terminal operations remain unavailable.
  67. Scoped PR4 acceptance includes online
  68. retained-Portal recovery and UI-assisted offline read-write opening; the tested offline opens
  69. required Siemens dialog dismissal. See [local-session support and limits](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/MULTIUSER_OPERATIONS_SUMMARY.md).
  70. `get_project_status` and `compile_check` advertise structured output schemas with contract version `1.0`. Their text and `structuredContent` contain the same canonical document; read the typed payload at `result.value`. Compiler errors set `success:false` while retaining diagnostics, with MCP `isError:false`. Oversized values are omitted whole with retry guidance. See the [standalone response contract](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/PROJECT_OPERATIONS_SUMMARY.md#standalone-status-and-compilation-contract) for migration details.
  71. Project-tree callers must use `v3.0.0` or newer: the v2 `startPath` input and bare nested-array response were removed rather than retained as aliases. See the [project operations reference](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/PROJECT_OPERATIONS_SUMMARY.md#browse_project_tree-v3) for the migration request, complete response envelope, selector reconstruction, continuation, limits, and recovery behavior.
  72. ## Write safety
  73. Every write tool validates input, pins the exact binding, mutates, verifies and audits in one call.
  74. Target resolution and tool-owned checks run in planning or beside mutation according to the domain.
  75. `plc_write`, `network_write`, `hmi_write` and `vci_write` never prompt. `library_write` asks once in
  76. read-write when the call includes global-library lifecycle; its content-only calls never prompt. On every write tool `dryRun:true` returns `phase:preview`
  77. without mutation or a confirmation prompt. In read-write every actual lifecycle call requires one form elicitation
  78. with explicit acceptance and boolean `confirm:true`, including calls with only info guards or no
  79. guards. Unsupported clients, decline, cancel, timeout, or transport failure deny with `access_denied`.
  80. Full mode satisfies acknowledge guards by policy without server elicitation. Block guards stop the
  81. call in every mode. Confirmation follows the access mode; the old startup switch was removed.
  82. See the [lifecycle reference](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/PROJECT_OPERATIONS_SUMMARY.md#lifecycle-operations)
  83. for guards, requests, responses, and recovery.
  84. **Consent depends on the MCP client.** Elicitation proves that the client returned an accepted
  85. answer, not that a person saw it. Project mutation and lifecycle tools retain conservative destructive hints; keep them
  86. out of client auto-approve lists if you want permission prompts on every call. `plc_write`,
  87. `network_write`, `hmi_write` and `vci_write` use `dryRun:true` for preview and execute by default, with no token and no server
  88. elicitation. Client permission prompts remain independent.
  89. Lifecycle uses pinned binding and transition checks;
  90. open/create can start unbound, save-as binds the resulting copy, and close clears the binding.
  91. Lifecycle audits every call, including dry runs and refusals, in `writes-yyyy-MM-dd.jsonl` under
  92. `%LOCALAPPDATA%\TiaMcpServer\audit`; audit v2 records confirmation by `user`, `policy`, or `none`.
  93. `plc_write`, `network_write`, `hmi_write`, `vci_write` and `library_write` also record one audit v2 per entered call, including previews and denials, with confirmation `none` in read-write and `policy` in full; SDK argument rejection before entry has no write audit. The legacy write audit stream was retired.
  94. The worker never attaches to the first enumerated TIA Portal or selects the first open project. It
  95. requires an exact path match or a genuinely sole candidate; multiple possible targets fail with
  96. `target_ambiguous` before Attach or mutation. The server refuses to start when `--project` or
  97. `TIA_MCP_PROJECT_PATH` is not an absolute `.ap21` or `.amc21` path. A configured `--project` path
  98. becomes write-ready only after a matching worker identity is observed. Later identity drift returns `binding_conflict` and
  99. invalidates the session until an explicit rebind.
  100. There are no implicit opens: only `open_project` and `create_project` open a project. Use
  101. `bind_project` for an already-open project. Worker ownership is lost across a detach; a reattached
  102. project is treated as UI-owned. Read-only never opens, creates, saves or closes a project, while
  103. explicit binding may switch the selected session. Project-tree cursors reject binding changes,
  104. including a switch away and back to the same path.
  105. `plc_write`, `network_write`, `hmi_write`, `vci_write` and `library_write` pin one verified project binding through any planning, ordered mutation, verification and audit, so a concurrent rebind cannot redirect a planned write. Network and HMI do not re-plan per item or perform worker read-back. HMI plans from one initial public-read evidence set per HMI; those reads are sequential and non-atomic. Both domains record completed items as `trusted` or `superseded`. `plc_write` blocks name collisions, `create_block` on an existing block, deleting the default tag table, and unreadable evidence before anything runs; deletes and address overlaps are reported as info.
  106. Lifecycle rejection has top-level `{category,message}` `error` and MCP `isError:true`. An attempted
  107. write or verification failure instead has `success:false`, `error:null`, and `isError:false`, with
  108. typed failure evidence in `result` or `verification`. A mutation may have succeeded despite failed
  109. verification; inspect state before retrying.
  110. `save_project_as` still requires `rebind:true`, and warnings stay separate from success/failure.
  111. Lifecycle's removed inputs and structured outputs are breaking changes staged for the redesign's
  112. final major release. The Network and PLC migrations are implemented, and the safety-token core and the
  113. generic batch tools are retired. This step does not publish a package.
  114. ## Architecture
  115. TIA Portal V21 ships its Openness API as .NET Framework 4.8 assemblies. Those assemblies use .NET Framework remoting APIs that cannot run correctly inside a .NET 10 process.
  116. This project therefore uses two processes:
  117. - `TiaMcpServer` - the .NET 10 MCP stdio server and .NET global tool host.
  118. - `TiaMcpServer.OpennessWorker` - a .NET Framework 4.8 worker process that loads `Siemens.Engineering.*` and talks to TIA Portal.
  119. The MCP host keeps one persistent .NET Framework 4.8 worker process attached to TIA Portal and exchanges newline-delimited JSON over stdin/stdout. Requests are serialized, and the worker restarts automatically after a crash or timeout. Siemens DLLs are never copied into this repository or the NuGet package; the worker resolves them from the local TIA Portal V21 installation.
  120. ## Quick start
  121. Install the server as a .NET global tool, check your environment, and register it with an MCP client:
  122. ```powershell
  123. dotnet tool install -g TiaMcpServer
  124. tia-mcp doctor
  125. tia-mcp install claude-code
  126. ```
  127. `tia-mcp doctor` validates Windows version, .NET runtimes, the TIA Portal installation, Openness
  128. assemblies, user-group membership, and host/worker compatibility before you connect anything. Run it
  129. first — it reports exactly which prerequisite is missing.
  130. | Prerequisite | Notes |
  131. | --- | --- |
  132. | Windows | Windows-only; the Openness API has no other host |
  133. | Siemens TIA Portal V21 | with Openness installed and enabled |
  134. | `Siemens TIA Openness` group | the current Windows user must be a member |
  135. | Framework-dependent global tool: stable .NET 10 SDK 10.0.400 or newer | provides `dotnet tool install` and the supported .NET 10 runtime |
  136. | .NET Framework 4.8 runtime | required by the Openness worker process |
  137. The framework-dependent `tia-mcp` global tool requires a supported .NET 10 runtime. The separate
  138. self-contained `win-x64` archive includes the host runtime. Neither installation method requires
  139. users to install the `ModelContextProtocol` NuGet package.
  140. Custom .NET integrations that compile directly against the C# MCP SDK must review the
  141. ModelContextProtocol 2.2 migration notes and retest protocol negotiation, tool schemas, and
  142. structured results. This custom-integration requirement is separate from the `browse_project_tree`
  143. v3 migration described above.
  144. Supported clients for `tia-mcp install`: Claude Code, Codex, OpenCode, MiMoCode. Servers register in
  145. **read-only** mode by default (nine tools); add `--access-mode read-write` for edits, compilation,
  146. and lifecycle with one prompt per actual call (twenty-one tools). Select `--access-mode full` for
  147. lifecycle without server elicitation (the same twenty-one tools).
  148. Binding to a specific project, every install option, and the full access-mode reference are in the
  149. [installation guide](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/guides/installation.md). To build from source instead of installing
  150. the published tool, see [building from source](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/development/building.md).
  151. ## Documentation
  152. **Using the server**
  153. - [Installation](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/guides/installation.md) — install, verify with `doctor`, register with a client, access modes
  154. - [MCP client configuration](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/guides/mcp-client-configuration.md) — client config reference, block path addressing and response size limits
  155. - [Troubleshooting](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/guides/troubleshooting.md) — common failures and verified TIA Portal V21 behavior
  156. - [Supported operations](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/SupportedOperations/README.md) — every operation by area, with parameters
  157. **Understanding the design**
  158. - [Architecture](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/ARCHITECTURE.md) — two-process topology, access enforcement, write safety, the canonical JSON seam
  159. **Building and contributing**
  160. - [Contributing](https://github.com/Czarnak/tia-portal-mcp/blob/main/CONTRIBUTING.md) — workflow, branch and commit conventions
  161. - [Building from source](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/development/building.md) — build, test, coverage, run locally
  162. - [Local MCP sandbox testing](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/development/local-mcp-testing.md) — the MCP Inspector test loop
  163. - [Packaging](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/development/packaging.md) — build the package, install a local build as `tia-mcp`
  164. **Direction**
  165. - [Roadmap](https://github.com/Czarnak/tia-portal-mcp/blob/main/ROADMAP.md) — directional priorities
  166. - [Network operations roadmap](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/roadmap/network-operations.md) — phased network tool delivery
  167. - [Export/import format roadmap](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/roadmap/export-import-format.md) — source-format exchange
  168. - [JSON contract roadmap](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/roadmap/json-contract.md) — one structured output contract across the tools
  169. - [Improvement log](https://github.com/Czarnak/tia-portal-mcp/blob/main/docs/IMPROVEMENT_LOG.md) — open follow-ups and completed engineering work
  170. ## Contributing
  171. Contributions are welcome. See [CONTRIBUTING.md](https://github.com/Czarnak/tia-portal-mcp/blob/main/CONTRIBUTING.md) for the development workflow and how to set up your environment. For architecture and build reference, see [AGENTS.md](https://github.com/Czarnak/tia-portal-mcp/blob/main/AGENTS.md).
  172. ## Security
  173. For how to report security vulnerabilities, see [SECURITY.md](https://github.com/Czarnak/tia-portal-mcp/blob/main/SECURITY.md).
  174. ## Check other tools
  175. - [TIA Portal V21 Git Add-In](https://github.com/Czarnak/tia-git-addin)
  176. - [Claude Code / Codex / Gemini plugin for TIA Portal development](https://github.com/Czarnak/totally-integrated-claude)

Ratings and comments

Sign in to rate this skill.

Sign in

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