Twincat Mcp
MCP server for TwinCAT automation: build, deploy, run TcUnit, and inspect PLC data through ADS from AI clients.
TwinCAT engineering, runtime diagnostics and workflows through three MCP tools. The server targets MCP 2026-07-28 using the official Python SDK 2.2.0.
| Public tool | Purpose |
|---|---|
twincat_search |
Find relevant operations and workflows; browse categories without loading every schema. |
twincat_describe |
Read full schemas, prerequisites and examples for up to five operation IDs. |
twincat_execute |
Validate and execute an operation, or inspect/cancel an existing job. |
The catalog contains 66 operations. Individual operations are not separate MCP tools.
Search does not dynamically register tools or change tools/list. The public execute
tool is conservatively annotated as potentially destructive; operation-specific
authorization is enforced by the server.
The application version is 2.3.0. See the release notes for changes and upgrade instructions. The supported interface consists of the three public tools and the operation catalog.
Install
Requires Windows, Python 3.10+, TwinCAT XAE, Visual Studio MSBuild, the .NET
Framework 4.7.2 targeting pack and Beckhoff's TcXaeMgmt PowerShell module.
Optional Scope operations require TE13xx and an automation worker built with
Scope support. ADS recording does not require TE13xx.
.\scripts\setup.ps1
.\scripts\install-mcp.ps1
Setup creates .venv, installs pinned direct dependencies, and builds
TcAutomation/bin/Release-v2/TcAutomation.exe with MSBuild. Reload the MCP server
through the client after installation.
For any stdio MCP client, use absolute paths:
{
"command": "C:/path/to/twincat-mcp/.venv/Scripts/python.exe",
"args": ["C:/path/to/twincat-mcp/mcp-server/server.py"]
}
Use install-mcp.ps1 -Workspace to merge the entry into the current workspace's
VS Code configuration. Other server entries are preserved.
Discover and execute
Call twincat_search:
{"query": "read PLC variables"}
Call twincat_describe:
{"operations": ["runtime.read_var_list"]}
Call twincat_execute:
{
"operation": "runtime.read_var_list",
"arguments": {
"amsNetId": "1.2.3.4.1.1",
"port": 851,
"symbols": ["MAIN.bRunning", "MAIN.nCount"]
},
"requestKey": "9454a153-481b-49ea-b749-cf1799ae7139"
}
The response contains a jobHandle, status and bounded progress. By default execute
waits up to one second for completion; waitSeconds can be 0–120. Small final
results are included inline. For unfinished work, wait without resubmitting:
{"operation": "job.wait", "arguments": {"jobHandle": "<returned handle>", "waitSeconds": 120}}
Large results remain in the receipt store. Read job.result using offset and
limit; concatenate its JSON text pages. The default page is 8,000 characters,
with a 16,000-character maximum. No full schema catalog or unlimited log stream
is sent to the model.
job.wait returns the current receipt on timeout with waitTimedOut:true;
job.get inspects it immediately. Cancelling a wait leaves the job running.
Supply a new UUID requestKey for each submitted operation.
system.status, context.status, safety.revoke, job.get, job.result and
job.cancel return immediately. These operations and job.wait do not require
a request key. After a lost
response, resend exactly the same operation, arguments and key: the original
receipt is returned without executing again. A key with different arguments is
rejected. Intentional repeats require new keys. The receipt store retains keys
across restarts; deleting the database ends that protection.
Engineering contexts and grants
Engineering operations use an explicit contextHandle. Open one with:
{
"operation": "context.open",
"arguments": {
"solutionPath": "C:/Projects/Machine/Machine.sln",
"amsNetId": "1.2.3.4.1.1",
"plcName": "PLC"
},
"requestKey": "<new UUID>"
}
From the project's README.