tia-portal-mcp

tia-portal-mcp

Scope

Direct TIA Portal interaction via MCP tools — no code generation required. Use MCP tools for exploration, inspection, and targeted single-step modifications. For bulk automation, looped operations, or scripted workflows, fall back to tia-openness-roadmap.

When MCP is the right choice

| Situation | Use | |---|---| | Explore project structure before writing code | MCP browse_project_tree | | Read a block to understand logic or generate code | MCP get_block_content | | Apply a focused, one-shot block edit | MCP update_block_logic | | List tags for context or documentation | MCP list_tag_tables | | Inspect hardware topology / IP addresses | MCP read_hardware_config | | Find unused or unreferenced objects | MCP read_cross_references | | Add a single device to the project | MCP search_equipment_catalog → add_network_device | | Check compile errors before or after edits | MCP compile_check | | Complex loops / bulk changes over many blocks | tia-openness-roadmap instead |

Safety convention

All MCP write tools are write-protected. They require a preview call first, then the write call must include both confirm: true and the preview response's safetyToken. Never invent or reuse a token. Tokens are short-lived, single-use, and bound to the target, requested input, project path, and current project state.

| Write tool | Required preview | |---|---| | update_block_logic | preview_update_block_logic | | create_tag_table / delete_tag_table | preview_create_tag_table / preview_delete_tag_table | | create_tag / update_tag / delete_tag | preview_create_tag / preview_update_tag / preview_delete_tag | | create_user_constant / update_user_constant / delete_user_constant | matching preview_*_user_constant tool | | add_network_device / configure_network_device | preview_add_network_device / preview_configure_network_device | | open_project / create_project / save_project / save_project_as / archive_project / close_project | matching preview_* lifecycle tool |

Tool reference

browse_project_tree

Recursively enumerates the project: devices, PLC software, block folders, blocks, tag tables, types.

| Parameter | Type | Required | Notes | |---|---|---|---| | projectPath | string | no | Path to .ap21 file; defaults to currently open project |

Returns JSON tree. Use returned Path values as blockPath input for other tools.

get_block_content

Exports a PLC block as a SIMATIC SD YAML document. Supports SCL, LAD, FBD, GRAPH, STL, and Data Blocks.

| Parameter | Type | Required | Notes | |---|---|---|---| | blockPath | string | yes | BlockName, PLC_1/BlockName, or PLC_1/Blocks/Folder/.../BlockName | | projectPath | string | no | |

Returns YAML string. Parse or display as-is; pass back (modified) to update_block_logic.

update_block_logic

Imports SIMATIC SD YAML to update or create a PLC block. Always call get_block_content first to obtain the current YAML before editing, unless creating a block from scratch. Then call preview_update_block_logic and show the diff/summary to the user before applying.

| Parameter | Type | Required | Notes | |---|---|---|---| | blockPath | string | yes | Target block path | | yamlContent | string | yes | Valid SIMATIC SD YAML | | confirm | bool | yes | Must be true to execute — default false is a no-op | | safetyToken | string | yes | Token returned by preview_update_block_logic for this exact request | | projectPath | string | no | |

list_tag_tables

Retrieves all PLC tag tables with tags and user constants.

| Parameter | Type | Required | Notes | |---|---|---|---| | plcName | string | no | Filter to a specific PLC | | projectPath | string | no | |

Returns JSON array of tag tables.

read_hardware_config

Exports hardware configuration and network topology: devices, rack modules, network interfaces, IP addresses, PROFINET device names, subnets, and IO systems.

| Parameter | Type | Required | Notes | |---|---|---|---| | projectPath | string | no | |

read_cross_references

Exports PLC cross-reference diagnostics with source objects, referenced objects, locations, access types, and reference types.

| Parameter | Type | Required | Notes | |---|---|---|---| | projectPath | string | no | | | plcName | string | no | Filter to a specific PLC | | filter | string | no | AllObjects \| ObjectsWithReferences \| ObjectsWithoutReferences \| UnusedObjects |

Use UnusedObjects to find dead code before cleanup.

search_equipment_catalog

Searches the installed TIA Portal V21 hardware catalog (including GSD/HSP packages) by type name, article number, or description. Always run before add_network_device.

| Parameter | Type | Required | Notes | |---|---|---|---| | query | string | yes | Free-text search | | projectPath | string | no | |

Returns entries with typeIdentifier values — copy the exact identifier into add_network_device.

add_network_device

Inserts a device from the hardware catalog into the project.

| Parameter | Type | Required | Notes | |---|---|---|---| | typeIdentifier | string | yes | Exact value from search_equipment_catalog | | deviceName | string | yes | Name for the new device in the project | | deviceItemName | string | no | Name for root device item; defaults to deviceName | | confirm | bool | yes | Must be true to execute | | safetyToken | string | yes | Token returned by preview_add_network_device | | projectPath | string | no | |

configure_network_device

Sets network identity and interface properties for a device already present in the project.

| Parameter | Type | Required | Notes | |---|---|---|---| | deviceName | string | yes | Device to configure | | ipAddress | string | no | IPv4 address | | subnetMask | string | no | Subnet mask | | pnDeviceName | string | no | PROFINET device name | | subnetName | string | no | Subnet to connect to | | ioSystemName | string | no | IO system to connect to | | confirm | bool | yes | Must be true to execute | | safetyToken | string | yes | Token returned by preview_configure_network_device | | projectPath | string | no | |

compile_check

Invokes TIA Portal compile on PLC software and returns errors and warnings.

| Parameter | Type | Required | Notes | |---|---|---|---| | blockPath | string | no | Compile a single block; omit to compile full PLC software | | plcName | string | no | Target a specific PLC; omit to compile all PLCs | | projectPath | string | no | |

Common execution patterns

Read and understand a block

1. browse_project_tree — find the block path
2. get_block_content(blockPath) — read SIMATIC SD YAML
3. Analyze or present the content

Modify a block

1. get_block_content(blockPath) — capture current YAML
2. Edit the YAML (preserve structure and indentation)
3. preview_update_block_logic(blockPath, yamlContent) — get diff and safetyToken
4. Show the preview to the user and confirm intent
5. update_block_logic(blockPath, yamlContent, confirm=true, safetyToken=...)
6. Review returned compile_check verification

Add and configure a new device

1. search_equipment_catalog(query) — find the exact typeIdentifier
2. preview_add_network_device(typeIdentifier, deviceName) — get safetyToken
3. Confirm device and name with user
4. add_network_device(typeIdentifier, deviceName, confirm=true, safetyToken=...)
5. preview_configure_network_device(deviceName, ipAddress, ...) — get safetyToken
6. configure_network_device(deviceName, ipAddress, ..., confirm=true, safetyToken=...)
7. Review returned read_hardware_config verification

Audit unused objects

1. read_cross_references(filter="UnusedObjects") — list unreferenced objects
2. Present findings to user before any removal action

Pre-ed