# TIA Openness MCP

**A local MCP server and JSON CLI for Siemens TIA Portal V20.**

`tiacli.exe` lets agents and scripts work with an installed TIA Portal through
the Openness API. It provides **65 tools** for projects, PLC programs, tags,
hardware, networks, HMI and libraries, plus an object bridge for discovering
and invoking supported public API operations.

Windows x64 · C# · .NET Framework 4.8 · MCP over stdio · v0.2.0

[Česky](README.cs.md) · [Setup](docs/SETUP.md) · [Tool reference](docs/TOOLS.md) ·
[Examples](docs/WORKFLOWS.md) · [Coverage and limitations](docs/COVERAGE.md)

## Quick start

Install TIA Portal V20 with Openness, the .NET Framework 4.8 Developer Pack,
and a .NET SDK capable of building this SDK-style project. Build on Windows:

```powershell
./scripts/Build.ps1
$exe = (Resolve-Path ./artifacts/tiacli-v0.2.0/tiacli.exe).Path
& $exe doctor
& $exe instances
& $exe plcs
& $exe blocks --plc PLC_1
```

Your Windows account must have active membership in `Siemens TIA Openness`.
TIA can request application authorization on first attachment and after a
rebuild. See [setup](docs/SETUP.md) for both steps.

Keep `Newtonsoft.Json.dll` and `tiacli.exe.config` beside the executable.
Siemens assemblies are resolved from your own TIA installation; they are
**not included in this repository**. Node.js is needed only for development
checks, documentation generation and tests.

## Connect an MCP client

Launch the executable with `mcp` as its only argument. For Codex, copy
[examples/codex-config.toml](examples/codex-config.toml) into the project's
local `.codex/config.toml` and replace the example executable path.
The local file is ignored by Git. This repository does not register a
global MCP server.

For clients using JSON `mcpServers` configuration, start from
[examples/mcp-config.json](examples/mcp-config.json). Configuration formats
vary; the server itself uses standard stdio.

Begin with `tia_doctor`, `tia_list_instances` and `tia_attach`. Attach once
and reuse the session. Select exact paths returned by list tools.

## Capabilities

| Area | Examples |
| --- | --- |
| Sessions and projects | Attach/start TIA, create/open/save/SaveAs/close, archive/retrieve |
| PLC programs | SCL/STL/UDT/DB generation, XML import/export, rename/delete, groups, compilation |
| PLC data | UDT operations, tag tables and tag CRUD, addresses and properties |
| Hardware and networks | Catalog search, station/module operations, subnets and node connections |
| HMI | Classic/Unified discovery, supported creation, properties, native import/export |
| Libraries | Project/global libraries, master copies and instantiation |
| API bridge | Type/signature discovery, handles, properties, attributes, services and method calls |

This is not a claim of complete implementation or testing of every Siemens
API operation. Delegates/events, `ref/out` parameters and arbitrary CLR
construction are unsupported. Products and licenses also determine which
operations work. See [coverage](docs/COVERAGE.md).

## CLI

All 65 tools can also be called from a short-lived CLI process:

```powershell
& $exe tools
& $exe call tia_list_tag_tables --json-file ./examples/list-tag-tables.json
```

CLI results are JSON. Object handles belong to one process/session;
use MCP for workflows sharing handles. See [CLI and MCP](docs/CLI-MCP.md).

## Development

```powershell
npm ci --ignore-scripts
npm run check
npm test
npm run docs:check
```

`npm run check` needs no TIA. `npm test` requires the built EXE and installed
V20 API, but does not attach to an open project. Live suites are separate
and perform real operations; read [testing](docs/TESTING.md) first.

## Documentation

- [Installation and troubleshooting](docs/SETUP.md)
- [CLI, MCP protocol and lifecycle](docs/CLI-MCP.md)
- [All tools](docs/TOOLS.md) · [machine-readable schemas](docs/tools.json)
- [Practical workflows](docs/WORKFLOWS.md)
- [API bridge, types and handles](docs/API-BRIDGE.md)
- [Architecture and source map](docs/ARCHITECTURE.md)
- [Tests](docs/TESTING.md) · [Known limitations](docs/COVERAGE.md)
- [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
- [Publishing to GitHub](docs/PUBLISHING.md) · [Changelog](CHANGELOG.md)

## License and dependencies

Original code and documentation are released under the [Unlicense](LICENSE):
you may use, modify, sell and redistribute them, including in closed-source
applications. Dependencies keep their own licenses; see
[third-party notices](THIRD_PARTY_NOTICES.md).

This is an independent community project, not affiliated with or endorsed
by Siemens. TIA Portal, SIMATIC and WinCC are Siemens product names.
You need your own installed and appropriately licensed Siemens products.

Operations can change engineering projects and, through supported generic
API methods, interact with online devices. Use project copies for experiments.
The project provides no safety certification or warranty.