Skip to main content
Glama

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 工具

工具

功能

describe_configuration

查看模式、允许读取的符号和限制,不连接 PLC

read_symbols

一次读取 1..128 个配置白名单符号

inspect_source

检查用户提供的 TwinCAT XML 文本,列出可编辑 ST 区段

preview_source_edit

替换一个 ST 声明或正文区段,返回新 XML 和统一差异,不写任何文件

inspect_scope

查看 Scope XML 中的采集符号和类型

create_scope_candidate

从使用者的 Scope 模板克隆新增采集项,返回候选 XML 和精确差异

preview_source_batch

带源哈希检查的多个 ST 区段修改预览

inspect_tmc / inspect_tmc_type

导出符号浏览与结构、数组、枚举等类型查询

generate_scope_project

通过本机 Scope API 生成带图表及绑定的完整 YT 工程

plan_scope_from_tmc

把明确选择的 TMC 叶变量转换为 Scope 信号清单

diagnose_environment

检查本机依赖;命令行也可用 twincat-mcp --doctor

read_runtime_state / describe_symbols / browse_runtime_symbols

状态、白名单元数据和单独启用的全符号浏览

read_typed_symbols / decode_tmc_value

根据明确布局解码结构、数组、枚举、字符串和时间类型

start_recording / recording_status / stop_recording

有时长、采样数和存储上限的只读轮询录制

read_recording_samples / export_recording_csv / analyze_recording

分页查看、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 生成说明。

真实只读采集(需自行配置)

  1. 在工程电脑上自行安装 Beckhoff TwinCAT ADS 运行环境,配置并核实已有路由。

  2. 将 examples/target.example.json 复制为 target.local.json。

  3. 填写自己的 AMS Net ID、PLC ADS 端口、读取超时、允许读取的完整符号名。

  4. 明确启用 enabled: true。默认示例禁用,全部零的占位 Net ID 不允许启用。

  5. 使用 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.ps1

Python 测试覆盖配置边界、禁止未授权符号、合成模式、源码修改及真实 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An 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.
      16
      40
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables local stdio-based MCP integration with InoProShop/CODESYS for project structure reading, POU editing with verified writes, compilation, task configuration, and persistent session recovery.
      4
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -