TiaMcp

MCP server for Siemens TIA Portal V21+ projects — reads and writes directly to TIA Portal via the Openness API, designed for a fast, LLM- and human-friendly workflow.

Special features that make TiaMcp fast for LLM’s and human-readable friendly:

• STL is read/written as text AWL
• PLC tables are converted to/from Excel-compatible CSV
• HMI tables are converted to/from Excel-compatible CSV
• HMI alarms are converted to/from Excel-compatible CSV
• GRAPH is converted to/from compact text DSL (Domain Specific Language)

Format reference

Each item line of list_project ends with the formats it can be read in, e.g. tag table 'Tags' [csv, xml]; pass such a line to read_source_tree to read those formats. A write uses the one format whose files were edited, and refuses an item edited in two.

All source is read and written as files in a source tree on disk, so an LLM reads only what it needs and edits with small diffs instead of passing whole blocks through its context.

Prerequisites

• TIA Portal V21 installed, with Openness access enabled for your Windows user (Openness API group membership).
• .NET Framework 4.8.

Building

dotnet build TiaMcp.sln

Produces src\TiaMcp.Host\bin\Debug\net48\TiaMcp.Host.exe, the MCP stdio server entry point. dotnet test TiaMcp.sln runs the unit tests (no TIA Portal needed).

Registering with Claude Code

Copy .mcp.json.example to .mcp.json and point command at wherever you extracted or built TiaMcp.Host.exe:

{
  "mcpServers": {
    "tia": {
      "command": "C:\\path\\to\\TiaMcp.Host.exe",
      "args": []
    }
  }
}

Tools

All MCP tools exposed by the server, grouped by area.

Connection & project

PLC blocks

PLC tag tables

PLC UDTs (data types)

HMI tags

HMI alarms

Source tree (reading and writing all source)

Full argument descriptions are on each tool via MCP [Description] attributes — see src\TiaMcp.Mcp\TiaTools.cs.

GRAPH (S7-GRAPH/SFC) blocks

GRAPH blocks read/write as a compact text DSL instead of raw graphical XML:

GRAPH_BLOCK "ExampleProcess_SFC"
INTERFACE
  VAR_INPUT ... END_VAR
END_INTERFACE
PREOPERATIONS ... END_PREOPERATIONS
SEQUENCE "Sequence1"
  STEP 100 "StepName" [INIT] MAX_TIME=T#10S WARN_TIME=T#9S
    ACTION S: #SomeOutput
    SUPERVISION: #cond1 AND NOT #cond2
    INTERLOCK: ...
  END_STEP
  TRANSITION 100 "Trans100": (#iq_Sensor.Status.InActive AND NOT #iq_NextStep.Enabled)
  BRANCHES ... END_BRANCHES
  CONNECTIONS
    STEP 100 -> TRANSITION 100
  END_CONNECTIONS
END_SEQUENCE
END_GRAPH_BLOCK

Only step/transition attributes, actions, and matched-by-number conditions are writable. Interface, PREOPERATIONS, BRANCHES, and CONNECTIONS (topology) are read-only in this version. GRAPH blocks must also be consistent (compiled) before they can be read or written at all — that’s a Siemens API requirement, not a TiaMcp restriction.

A new .graph.il file in the source tree is created by cloning an existing GRAPH block of the PLC and reshaping it — Openness has no from-scratch GRAPH creation API.

Source tree

read_source_tree exports PLC blocks, tag tables, UDTs and alarm text lists, WinCC Unified HMI tag tables and alarms, and classic WinCC screens, screen templates, pop-up screens, tag tables and text lists to disk, in folders mirroring the TIA Portal project tree — the whole project, or only the items or groups you name:

/
  /
    Program blocks/
      /
        Main.s7dcl
        Main.s7res
    PLC tags/
      /
        Default tag table.csv
    PLC data types/
      /
        SomeUdt.s7dcl
    PLC alarm text lists/
      Textlist_ErrorsMessages.csv
  /
    HMI tags/
      /
        Default tag table.csv
    HMI alarms/
      DiscreteAlarms.csv
      AnalogAlarms.csv
      AlarmClasses.csv
  /
    HMI tags//Tags.xml
    Screens//Main.xml
    Screen templates//Template.xml
    Pop-up screens//Popup.xml
    Text lists/States.xml
  _export_summary.txt
  _manifest.json

Read and edit the files with your own file tools, then call write_source_tree. It writes back only what changed since the read — edited files, plus new files as new blocks, UDTs or tag tables — in dependency order, and then reads the written items back so the files show what TIA Portal made of them. Removing a row from a tag table CSV deletes that tag; deleting a file does not delete the item (use the delete_* tools).

PLC alarm text lists: one CSV per user list (From, To, one Text [language] column per project language). TIA Portal’s Excel import replaces whole lists, so a write starts from a fresh export, changes only the lists being written and imports that; removing a row deletes that entry (not when writing a tree read from another project). Lists can’t be created through Openness - create a new list in TIA Portal first. System lists (SYSTEM_*) are not exported.

Classic WinCC objects are native Openness XML (the DocumentInfo block is left out so an unchanged object reads back identically). They are written in dependency order (text lists, tag tables, templates and pop-ups, screens); a screen whose `` is already used by another screen is refused before the import, since TIA Portal V21 terminates itself on that. Graphic lists are not exported: exporting one crashed TIA Portal V21 (InvalidCastException in UpdateOpenLinks); a full read reports them as SKIPPED.

_manifest.json (version 2; an older version 1 manifest is still read) records what each item looked like when it was read, and in which formats. An item that was changed in TIA Portal since then is refused rather than overwritten (force overrides this). A tree read from one project can also be written in full into another, e.g. to restore it into an empty PLC.

License

AGPL-3.0 (see LICENSE). Contributions require signing the CLA — see CONTRIBUTING.md.

Not (yet) supported

• Hardware config.
• Explicit block numbering (manual vs. automatic, specific number).

Known limitations

• A block with STL embedded in a mixed FBD/LAD/SCL block can only be written through its raw .xml; whole-block STL is fully supported (see the STL section above).
• GRAPH blocks can only be created by cloning an existing one (see the GRAPH section above), not from scratch.
• Classic WinCC (Comfort/Advanced/RT Advanced): alarms are not reachable through Openness; graphic lists are skipped (export crashes TIA Portal V21); objects can’t be renamed or deleted through TiaMcp yet.
• PLC alarm text lists: only existing user lists can be written; the screen-number check for classic screens exports every screen once per write (about a minute for ~50 screens).