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-edit compile baseline

1. compile_check — record baseline errors/warnings
2. Apply changes
3. compile_check again — compare to baseline