EtherCAT MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@EtherCAT MCP Server Scan the EtherCAT bus and tell me which slaves are connected and their states."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
EtherCAT MCP Server
面向工业自动化与机器人控制的 EtherCAT Model Context Protocol (MCP) 服务。让 Claude Code、Codex CLI、Antigravity、Cursor 等 AI 工具能够直接与 EtherCAT 现场总线交互,实现从站拓扑扫描、ESM 状态机调度、CoE (CANopen over EtherCAT) SDO 读写、PDO 周期过程数据交互、CiA 402 伺服运动控制以及总线健康诊断。
内置高保真虚拟总线仿真器,开箱即用,无需真实硬件或专用网卡权限即可完成全流程调试与闭环测试。
🌟 核心特性
🚀 全面支持标准 ESM 状态机:无缝调度总线与各从站的
INIT、PRE-OP、BOOT、SAFE-OP、OP状态转换与 AL 错误复位。⚡ CoE 对象字典全功能支持:任意读取/写入 SDO 索引与子索引(支持十六进制如
0x6040、0x1018与十进制)。🔄 PDO 周期数据交互:实时读取数字量/模拟量输入、伺服编码器位置与状态字;高速下发数字量输出与运动指令。
🦾 内置 CiA 402 伺服驱动状态机:提供高层运动控制工具(电机使能、停机、急停、故障复位、点动/位置定位、速度模式)。
🌐 零门槛高仿真虚拟总线:自带由倍福(Beckhoff)与汇川(Inovance)经典设备构成的 5 从站虚拟链路,离线即测。
🔌 硬件网关无缝接入:支持无缝对接原生 EtherCAT 主站后台(SOEM daemon / IgH EtherCAT Master / TwinCAT ADS 桥接)。
Related MCP server: codesys-mcp-server
🏗️ 架构图
┌────────────────────────────────────────────────────────┐
│ AI Assistants (Claude / Codex / Antigravity) │
└───────────────────────────┬────────────────────────────┘
│ MCP Protocol (stdio)
▼
┌────────────────────────────────────────────────────────┐
│ ethercat-mcp Server │
│ - 12 Native MCP Tools (ESM, SDO, PDO, CiA 402) │
└─────────────┬────────────────────────────┬─────────────┘
│ (Simulation Mode) │ (Hardware Mode)
▼ ▼
┌───────────────────────────┐ ┌─────────────────────────┐
│ Built-in Virtual Bus │ │ Native Master Gateway │
│ - EK1100 (Bus Coupler) │ │ (SOEM / IgH / ADS) │
│ - EL1008 (8-Ch DI) │ └───────────┬─────────────┘
│ - EL2008 (8-Ch DO) │ │ Ethernet Raw Socket
│ - EL3064 (4-Ch AI 0-10V) │ ▼
│ - SV660N (CiA 402 Servo) │ ┌─────────────────────────┐
└───────────────────────────┘ │ Real EtherCAT Slaves │
└─────────────────────────┘🛠️ MCP 工具列表 (Tools)
工具名称 | 功能描述 | 典型参数示例 |
| 扫描总线上的所有从站设备并输出厂商、型号代码、固件版本、序列号及状态 |
|
| 查询特定从站的软硬件详情、CoE 对象字典映射及 PDO 配置 |
|
| 输出 EtherCAT 总线物理网线级联拓扑关系与端口链路状态 |
|
| 查询总线主站或指定从站的 ESM 当前状态与 AL 状态码 |
|
| 请求总线或特定从站执行状态迁移 ( |
|
| 读取 CoE 对象字典条目(支持十六进制索引) |
|
| 向 CoE 对象字典写入参数值 |
|
| 读取周期过程输入映像 (TxPDO: 数字量/模拟量/当前位置速度) |
|
| 下发周期过程输出映像 (RxPDO: 继电器开闭/控制字/目标位置) |
|
| 获取总线通信质量报告(周期时间、抖动、丢包率、CRC 错误) |
|
| 复位从站 AL 报警及驱动器故障状态 |
|
| 高层 CiA 402 伺服电机控制快捷工具(使能/去使能/回零/定位) |
|
⚡ 快速接入与配置
1. Claude Code
claude mcp add -s user ethercat -- npx -y ethercat-mcp2. Codex CLI
codex mcp add ethercat -- npx -y ethercat-mcp3. Claude Desktop
在 claude_desktop_config.json 中追加:
{
"mcpServers": {
"ethercat": {
"command": "npx",
"args": ["-y", "ethercat-mcp"]
}
}
}4. 真实硬件网关模式 (SOEM / TwinCAT ADS)
若要连接外部工业总线主站守护进程:
npx ethercat-mcp --hardware --endpoint=http://127.0.0.1:8088🤖 典型 AI 交互示例
连接完成后,您可以直接在 AI 中输入自然语言:
扫描总线拓扑:
“帮我扫描一下当前 EtherCAT 总线挂载了哪些设备,现在的通信状态是什么?”
电机上电与位置运动:
“把 4 号从站伺服驱动器使能上电,并控制它运动到位置 25000 脉冲。”
读取 IO 终端信号:
“读取 1 号从站 EL1008 的所有输入通道电平,以及 3 号从站当前的模拟量电压。”
故障诊断与排除:
“检查总线是否有丢包或者 CRC 校验错误,如果驱动器报错请帮我读取 0x603F 并复位报警。”
💻 本地构建与测试
# 克隆仓库
git clone https://github.com/LckAndLove/ethercat-mcp.git
cd ethercat-mcp
# 安装依赖
npm install
# 类型检查与编译
npm run check
npm run build
# 运行自动化单元测试
npm test📄 License
MIT License © 2026 LckAndLove
Available Tools
12 toolsdrive_controlC
High-level CiA 402 Servo Drive Motion Control (enable, disable, quick_stop, fault_reset, move_velocity, move_position).
Inputs: action (required), target, slaveIndex.
get_diagnosticsA
Get EtherCAT bus diagnostic metrics including frame loss, jitter, cycle time, CRC errors, and active AL errors.
Inputs: no named parameters.
get_esm_stateA
Query the EtherCAT State Machine (ESM) state (INIT, PREOP, BOOT, SAFEOP, OP) for the bus or a specific slave.
Inputs: slaveIndex.
get_slave_infoA
Get detailed information, SDO object dictionary, and PDO mappings for a specific slave device.
Inputs: slaveIndex (required).
get_topologyA
Get the physical cable connection topology of the EtherCAT bus (port-to-port connections).
Inputs: no named parameters.
read_pdoB
Read cyclic process data (TxPDO inputs: Digital Inputs, Analog Voltages, Motor feedback position/velocity).
Inputs: slaveIndex.
read_sdoA
Read a CANopen over EtherCAT (CoE) SDO object by Index (e.g. 0x6041 or "0x6041") and SubIndex.
Inputs: index (required), slaveIndex (required), subIndex.
reset_errorB
Reset slave AL errors, clear alarms, and perform CiA 402 drive fault reset.
Inputs: slaveIndex.
scan_slavesA
Scan the EtherCAT bus and list all connected slave devices with identity, current state, and port links.
Inputs: no named parameters.
set_esm_stateB
Request an EtherCAT State Machine (ESM) transition (INIT, PREOP, BOOT, SAFEOP, OP) for a slave or all slaves.
Inputs: targetState (required), slaveIndex.
write_pdoB
Write cyclic output process data (RxPDO outputs: Digital Outputs, motor target position/controlword).
Inputs: values (required), slaveIndex (required).
write_sdoC
Write a value to a CANopen over EtherCAT (CoE) SDO object by Index and SubIndex.
Inputs: index (required), value (required), slaveIndex (required), subIndex.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool maps to a distinct resource/action (SDO vs PDO vs ESM vs diagnostics), and descriptions clarify the boundaries. Minor overlap exists between reset_error and drive_control's fault_reset action, and set_esm_state vs reset_error both touch fault/alarm clearing, but an agent can reasonably distinguish them.
Almost all tools use a clean verb_noun pattern (read_sdo, write_pdo, get_diagnostics, scan_slaves, set_esm_state). The lone outlier is drive_control, which inverts to noun_verb and slightly stands out.
12 tools is well within the ideal 3-15 range and each covers a meaningful EtherCAT operation (discovery, state machine, SDO/PDO I/O, diagnostics, drive control). No filler tools are present.
The surface covers the full master lifecycle: bus scan, topology, ESM get/set, SDO and PDO read/write, diagnostics, error reset, and CiA 402 drive control. Gaps are minor — no explicit PDO mapping/configuration write or slave EEPROM/firmware operations — but core workflows are fully supported.
Related MCP Connectors
Design circuits, simulate and verify embedded firmware, and lay out PCBs with AI agents.
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
Run, build, and validate firmware on virtual hardware from your AI agent. Hardware knowledge corpus.
Connect your AI to your own devices, 3D printers, factory tools and a shared agent task pool.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with B\&R Automation Studio projects by building code, running ARsim simulators, and reading or writing OPC UA variables. It facilitates industrial automation development and real-time variable integration through natural language commands.17MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to automate CODESYS V3 PLC development, including project editing, builds, library and alarm management, online variable read/write/force operations, and CODESYS documentation search via MCP.4MIT
- AlicenseNot gradedqualityBmaintenanceExposes 20 vehicle-security tools to AI coding agents such as Claude Code and Cursor, enabling them to send, fuzz, and analyze CAN frames, run UDS diagnostics and seed-key handshakes, simulate DoIP ECUs, and decode ISO-TP, J1939, DBC, and V2X data. Everything runs against a virtual CAN bus, so no vehicle or hardware is required.1MIT
- AlicenseCqualityAmaintenanceEnables an AI agent to drive a Beckhoff TwinCAT 3 setup end to end: read and write live PLC variables and system state over ADS, manage files and processes on the target IPC, build and edit projects through the XAE automation interface, capture and analyze long-running signal recordings, run scripted test benches and TcUnit suites, and look up the official Beckhoff Infosys documentation. Runs as a single Python process on the engineering PC with read-only, guarded, and full safety modes plus human-in-the-loop confirmation for destructive operations.61711MIT