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
browse_project_tree— find the block pathget_block_content(blockPath)— read SIMATIC SD YAML- Analyze or present the content
Modify a block
get_block_content(blockPath)— capture current YAML- Edit the YAML (preserve structure and indentation)
preview_update_block_logic(blockPath, yamlContent)— get diff andsafetyToken- Show the preview to the user and confirm intent
update_block_logic(blockPath, yamlContent, confirm=true, safetyToken=...)- Review returned
compile_checkverification
Add and configure a new device
search_equipment_catalog(query)— find the exacttypeIdentifierpreview_add_network_device(typeIdentifier, deviceName)— getsafetyToken- Confirm device and name with user
add_network_device(typeIdentifier, deviceName, confirm=true, safetyToken=...)preview_configure_network_device(deviceName, ipAddress, ...)— getsafetyTokenconfigure_network_device(deviceName, ipAddress, ..., confirm=true, safetyToken=...)- Review returned
read_hardware_configverification
Audit unused objects
read_cross_references(filter="UnusedObjects")— list unreferenced objects- Present findings to user before any removal action