twincat-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
twincat-mcp
TwinCAT 工程检查与候选编辑、离线 PLC 编译、Scope 生成及 ADS 只读诊断的本地 MCP 服务。
0.2.0 已补齐本轮确认的工程、Scope 和只读诊断工具;能力与边界见 ROADMAP。 包含工程/TMC 检索、候选导出、隔离离线编译、完整 Scope 生成和只读录制;实测范围见 VALIDATION。
Read-only ADS diagnostics and offline TwinCAT source-edit previews through MCP stdio. Independent community tooling; not an official Beckhoff product.
安装和演示
需要 Python 3.10+。演示和离线 XML 工具不需要 TwinCAT;真实 ADS 采集仅支持 Windows。
git clone https://github.com/pcyamzguy12138/twincat-mcp.git
cd twincat-mcp
python -m venv .venv
.venv\Scripts\python.exe -m pip install .
.venv\Scripts\twincat-mcp.exe --demo最后一条命令启动 stdio MCP 服务,等待客户端 JSON-RPC 输入,不是交互式命令行。
MCP 客户端配置参考 examples/mcp-client.example.json:
把 command 改为本机 .venv/Scripts/twincat-mcp.exe 的绝对路径。
演示值是固定合成数据,结果明确标记 demo: true,不会加载 ADS DLL。
Related MCP server: qwispr
MCP 工具
工具 | 功能 |
| 查看模式、允许读取的符号和限制,不连接 PLC |
| 一次读取 1..128 个配置白名单符号 |
| 检查用户提供的 TwinCAT XML 文本,列出可编辑 ST 区段 |
| 替换一个 ST 声明或正文区段,返回新 XML 和统一差异,不写任何文件 |
| 查看 Scope XML 中的采集符号和类型 |
| 从使用者的 Scope 模板克隆新增采集项,返回候选 XML 和精确差异 |
| 带源哈希检查的多个 ST 区段修改预览 |
| 导出符号浏览与结构、数组、枚举等类型查询 |
| 通过本机 Scope API 生成带图表及绑定的完整 YT 工程 |
| 把明确选择的 TMC 叶变量转换为 Scope 信号清单 |
| 检查本机依赖;命令行也可用 |
| 状态、白名单元数据和单独启用的全符号浏览 |
| 根据明确布局解码结构、数组、枚举、字符串和时间类型 |
| 有时长、采样数和存储上限的只读轮询录制 |
| 分页查看、CSV 导出、统计和布尔边沿分析 |
指定 --project-root <只读工程目录> 后,还可使用 inspect_project、
read_project_source、search_project、inspect_project_references、
preview_project_edits、export_project_candidates、browse_project_symbols 和 inspect_project_type。
另用 --build-root <独立输出目录> 启用 compile_plc_project,编译副本并返回错误位置。
路径范围、搜索证据和格式限制见 工程工具。
inspect_source 和 preview_source_* 接受文本;工程工具使用启动时固定的目录。编码保存规则和受保护对象边界见 源码格式说明。
增补 Scope 使用同类型采集模板;完整新建使用安装的厂商 API 并验证通道绑定。
两种路径均不编造厂商格式。见 Scope 生成说明。
真实只读采集(需自行配置)
在工程电脑上自行安装 Beckhoff TwinCAT ADS 运行环境,配置并核实已有路由。
将
examples/target.example.json复制为target.local.json。填写自己的 AMS Net ID、PLC ADS 端口、读取超时、允许读取的完整符号名。
明确启用
enabled: true。默认示例禁用,全部零的占位 Net ID 不允许启用。使用
twincat-mcp --config <target.local.json绝对路径>启动。
配置在启动时读取并固定,工具调用不能修改目标、路由或白名单。符号匹配区分大小写。
使用本机 Windows PowerShell 和已安装的 TcAdsDll.dll;不附带厂商 DLL,不绕过 PowerShell 执行策略。
单次快照总等待上限 60 秒,同时仅一项快照操作,可与一项持续录制并存;超时终止桥接进程。
读取内核只暴露状态、符号版本、名称元数据查询和 SUMUP_READ。
AdsSyncReadWriteReqEx2 仅用于 0xF009 名称查询及 0xF080 批量读,发送的是符号名称/地址/长度,不是写 PLC 数值。
没有变量写入、写控制状态、PLC 方法调用、下载、Activate Configuration、重启或添加路由接口。
缺失变量、未知结构、通讯错误和版本变化会显式标错;符号版本变化时整批值作废。
读数不是同一 PLC 扫描周期的原子快照,不能替代 Scope 时序分析,也不证明磁盘源码与在线版本一致。
录制把 JSONL 和元数据保存到 --recording-root 或返回的临时目录;导出、触发和存储限制见 只读诊断。
本服务不额外上传数据;MCP 客户端如何使用返回的符号和数值取决于客户端配置。
测试
.venv\Scripts\python.exe -m unittest discover -s tests -v
powershell -NoProfile -File tests/Test-Offline.ps1Python 测试覆盖配置边界、禁止未授权符号、合成模式、源码修改及真实 MCP stdio 客户端往返。 C# 测试通过模拟传输覆盖断线、缺失变量、版本变化、截断响应、类型解码及只读 API 检查。 常规测试不加载 ADS DLL、不连接 PLC。厂商 Scope API 和 XAE 编译单独验证;实际版本、结果和未覆盖项见 VALIDATION。
来源与公开内容
C# ADS 内核提取自作者既有只读采集工具,公开版统一通用命名空间。
MCP 服务、操作员白名单、合成演示及文本源码修改预览是本次新增包装。
公开仓库不含客户 PLC/HMI/NC/Boot 工程、真实变量清单、采集结果、现场截图、设备路由、凭据或原工作区历史。
配置、日志和输出目录已列入 .gitignore;提交前仍应人工检查内容。
使用官方 MCP Python SDK v1 维护分支,依赖明确限制为 mcp>=1.28,<2。
协议采用 MCP stdio,不开放网络监听端口。
MIT License,见 LICENSE。Beckhoff / TwinCAT 商标归其所有者。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Lean 4 MCP server: compile, prove theorems, and formalize math with Mathlib.
Ovanek MCP: Model Context Protocol server for Ovanek platform tools; writes are dry-run by default.
Read-only MCP for DualSoft AAS 3.0 / AASX specs, DS2 PLC control docs, and 3D line examples.
1One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server for validating, auto-fixing, and scaffolding TwinCAT 3 XML files using deterministic code quality tools and IEC 61131-3 OOP checks. It enables AI assistants to perform structural validation, apply safe fixes, and generate canonical code skeletons for industrial automation projects.1640MIT
- FlicenseNot gradedqualityBmaintenanceEnables MCP clients to analyze call graphs, run Grover-ranked code searches, generate boundary test cases, get refactoring suggestions, and inspect quantum backends through stdio JSON-RPC tools.2-
- AlicenseNot gradedqualityBmaintenanceEnables local stdio-based MCP integration with InoProShop/CODESYS for project structure reading, POU editing with verified writes, compilation, task configuration, and persistent session recovery.4MIT
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients and AI coding agents to query a running editor instance for real-time LSP diagnostics, symbol/type information, references, file opening, and workspace-wide symbol renaming, avoiding slow tsc/eslint runs.-