TIA-Portal MCP-Server

A MCP server which connects to Siemens TIA Portal.

Features

• Connect to a TIA Portal instance
• Browse and interact with TIA Portal projects
• Perform basic project operations from within VS Code

Requirements

• .net Framework 4.8 installed
• Siemens TIA Portal V20 installed and running on your machine
• Check if under Environment Variables/User variable for user <name> the variable TiaPortalLocation is set to C:\Program Files\Siemens\Automation\Portal V20
• User must be in Windows User Group Siemens TIA Openness

TIA-Portal Versions

• V20 is the default version.
• Previous versions are also supported, but must use the --tia-major-version argument to specify the version.
• Export as documents (.s7dcl/.s7res) via ExportAsDocuments/ExportBlocksAsDocuments requires TIA Portal V20 or newer.
• Import from documents (.s7dcl/.s7res) via ImportFromDocuments/ImportBlocksFromDocuments also requires TIA Portal V20 or newer.

Known Limitations

• As of 2025-09-02: Importing Ladder (LAD) blocks from SIMATIC SD documents requires the companion .s7res file to contain en-US tags for all items; otherwise import may fail. This is a known limitation/bug in TIA Portal Openness.
• ExportBlock requires a fully qualified blockPath like Group/Subgroup/Name. If only a name is provided, the MCP server returns InvalidParams and may include suggestions for likely full paths.

Testing

• See tests/TiaMcpServer.Test/README.md for environment prerequisites and test asset setup.
• Standard command: dotnet test (run from the repo root).
• Test execution policy: offer to run tests, but only execute after explicit user confirmation. Details in AGENTS.md.

Contributing

• See agents.md for guidance on working with agentic assistants and the test execution policy (offer to run tests only with explicit user confirmation).

Error Handling (ExportBlock)

• The Portal layer throws PortalException with a short message and PortalErrorCode (e.g., NotFound, ExportFailed), and attaches softwarePath, blockPath, exportPath in Exception.Data while preserving InnerException on export failures.
• The MCP layer maps these to McpException codes. For ExportFailed, it includes a concise reason from the underlying error; for NotFound, it returns InvalidParams and may suggest likely full block paths if a bare name was provided.
• Consistency required: TIA Portal never exports inconsistent blocks/types. Single export returns InvalidParams with a message to compile first. Bulk export skips inconsistent items and returns them in an Inconsistent list alongside Items.
• Standardization: Exception context metadata is attached in a single catch per portal method right before rethrow, not at inline throw sites. See docs/error-model.md.
• This standardized pattern currently applies to ExportBlock and will expand incrementally.

Transports

• Supported today: stdio
  • Program wires AddMcpServer().WithStdioServerTransport().
  • For stdio, logs must go to stderr to avoid corrupting JSON-RPC.
• Available via SDK: stream (custom streams)
  • The SDK exposes WithStreamServerTransport(Stream input, Stream output) which can be used to host over TCP sockets or other streams.
  • Not wired in this repo yet.
• HTTP/Streamable HTTP: not implemented yet
  • The current ModelContextProtocol .NET package in use (0.3.0-preview.4) does not provide an HTTP server transport out of the box.
  • Plan (see TODO): add --transport http, --http-prefix, and --http-api-key, host with HttpListener, and route POST /mcp to the MCP handlers. Later align with MCP Streamable HTTP spec.

Copilot Chat

• Example mcp.json, when using VS Code extension TIA-Portal MCP-Server and TIA-Portal V18

  {
      "servers": {
          "vscode-tiaportal-mcp": {
          "command": "c:\\Users\\<user>\\.vscode\\extensions\\jheilingbrunner.vscode-tiaportal-mcp-<version>\\srv\\net48\\TiaMcpServer.exe",
          "args": [
              "--tia-major-version",
              "18"
          ],
          "env": {}
          }
      }
  }

Claude Desktop

• Create/Edit to add/remove server to C:\Users\<user>\AppData\Roaming\Claude\claude_desktop_config.json:

  {
    "mcpServers": {
      "vscode-tiaportal-mcp": {
        "command": "<path-to>\\TiaMcpServer.exe",
        "args": [],
        "env": {}
      }
    }
  }