Modbus MCP Auto

Modbus TCP MCP服务器

用于与Modbus TCP设备交互的综合模型上下文协议（MCP）服务器。该服务器使LLM能够连接到工业Modbus TCP设备，并对其进行读写操作。

特性

• 连接管理：建立和维护与Modbus TCP设备的连接
• 读取操作：读取保持寄存器、输入寄存器、线圈和离散输入
• 写入操作：写入单个或多个寄存器/线圈
• 数据类型支持：支持uint16、int16、uint32、int32、float32和bool
• 设备信息：查询设备标识（如果支持）
• 诊断：运行全面的诊断测试
• 连接池：高效的连接重用
• 错误处理：清晰、可操作的错误消息

安装

需求

• Python 3.8或更高版本
• MCP Python SDK
• pymodbus库

再进行

pip install mcp pymodbus --break-system-packages

或者，如果您正在使用虚拟环境：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install mcp pymodbus

用法

运行服务器

python modbus_tcp_mcp.py

服务器作为基于stdio的MCP服务器运行，并等待来自MCP客户端的请求。

使用Claude Desktop进行配置

将此添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "modbus_tcp": {
      "command": "python",
      "args": ["/path/to/modbus_tcp_mcp.py"]
    }
  }
}

可用工具

1.modbus_connect

连接到Modbus TCP设备。

参数:

• host （str）：IP地址或主机名（例如“192.168.1.100”）
• port （int，可选）：TCP端口（默认值：502）
• timeout （浮点数，可选）：连接超时（秒）（默认值：10.0）
• unit_id （int，可选）：Modbus从站/单元ID（默认值：1）

示例:

Connect to PLC at 192.168.1.50

2.modbus_read_registers

从Modbus寄存器或线圈读取值。

参数:

• host （str）：设备IP地址
• register_type （str）：“保持”、“输入”、“线圈”或“离散”
• start_address （int）：起始寄存器地址（从0开始）
• count （int）：要读取的寄存器数量
• data_type （str，可选）：“uint16”，“int16”，“uint32”，“int 32”，“float32”，”bool”（默认值：“uint16”）
• port （int，可选）：TCP端口（默认值：502）
• unit_id （int，可选）：从属ID（默认值：1）
• response_format （str，可选）：“markdown”或“json”（默认：“markdown”）

示例:

Read holding registers 100-105 from PLC at 192.168.1.50 as float32

3.modbus_write_register

将值写入单个Modbus寄存器或线圈。

参数:

• host （str）：设备IP地址
• address （int）：要写入的注册地址
• value （int/flot/bool）：要写入的值
• register_type （str，可选）：“holding”或“coil”（默认：“hold”）
• data_type （str，可选）：用于编码的数据类型（默认值：“uint16”）
• port （int，可选）：TCP端口（默认值：502）
• unit_id （int，可选）：从属ID（默认值：1）
• response_format （str，可选）：“markdown”或“json”（默认：“markdown”）

示例:

Write 1500 to holding register 100 on PLC at 192.168.1.50

4.modbus_write_multiple_registers

将值写入多个连续的寄存器或线圈。

参数:

• host （str）：设备IP地址
• start_address （int）：起始寄存器地址
• values （list）：要写入的值列表
• register_type （str，可选）：“holding”或“coil”（默认：“hold”）
• data_type （str，可选）：用于编码的数据类型（默认值：“uint16”）
• port （int，可选）：TCP端口（默认值：502）
• unit_id （int，可选）：从属ID（默认值：1）
• response_format （str，可选）：输出格式（默认：“markdown”）

示例:

Write values [100, 200, 300] to holding registers 40-42 on device 192.168.1.50

5.modbus_device_info

查询设备标识信息。

参数:

• host （str）：设备IP地址
• port （int，可选）：TCP端口（默认值：502）
• unit_id （int，可选）：从属ID（默认值：1）
• response_format （str，可选）：输出格式（默认：“markdown”）

示例:

Get device information from PLC at 192.168.1.50

6.modbus_诊断学

在设备上运行诊断测试。

参数:

• host （str）：设备IP地址
• port （int，可选）：TCP端口（默认值：502）
• unit_id （int，可选）：从属ID（默认值：1）
• test_read （bool，可选）：执行测试读取（默认值：True）
• response_format （str，可选）：输出格式（默认：“markdown”）

示例:

Run diagnostics on Modbus device at 192.168.1.50

7.modbus_diisconnect

关闭与设备的连接。

参数:

• host （str）：设备IP地址
• port （int，可选）：TCP端口（默认值：502）

示例:

Disconnect from PLC at 192.168.1.50

注册类型

保持寄存器（功能代码3/6/16）

• 访问：读/写
• 尺寸：16位（2字节）
• 使用：通用数据存储、配置、设定点

输入寄存器（功能代码4）

• 访问：只读
• 尺寸：16位（2字节）
• 使用：传感器读数、模拟输入、状态数据

线圈（功能代码1/5/15）

• 访问：读/写
• 尺寸：1位（布尔值）
• 使用：数字输出、控制信号、二进制标志

离散输入（功能代码2）

• 访问：只读
• 尺寸：1位（布尔值）
• 使用：数字输入、开关、二进制传感器

数据类型

寻址

此服务器使用 基于0的寻址 （协议寻址）：

• 注册0=地址0
• 寄存器1=地址1
• 等等

如果您的设备文档使用基于1的寻址或偏移寻址（例如，40001-49999用于保持寄存器），请减去偏移：

• 持有登记簿40001→ 地址0
• 输入寄存器30001→ 地址0
• 线圈00001→ 地址0

例子

示例1：读取温度传感器

Read input register 100 from device 192.168.1.50 as float32

示例2：控制继电器

Write True to coil 5 on device 192.168.1.50

示例3：读取多个值

Read holding registers 0-9 from PLC at 192.168.1.100

示例4：写入配置

Write values [1000, 2000, 3000, 4000, 5000] to holding registers 200-204 on device 192.168.1.50

示例5：设备诊断

Run diagnostics on device 192.168.1.50 to check connectivity and response time

错误处理

服务器提供清晰、可操作的错误消息：

• 连接失败：检查IP地址、端口和网络连接
• 注册地址无效：验证地址是否在设备范围内
• Modbus异常：设备特定错误，请检查设备文档
• 超时：设备没有响应，请检查设备状态
• 只读寄存器：无法写入输入/离散寄存器

最佳实践

1. 首先测试连接性：使用 modbus_connect 在其他操作之前
2. 使用适当的数据类型：将数据类型与设备的配置相匹配
3. 处理大型读取：如果需要，可以分块读取寄存器（寄存器最多125个）
4. 关闭连接：使用 modbus_disconnect 当释放资源时
5. 运行诊断：使用 modbus_diagnostics 解决问题

故障排除

连接超时

• 验证设备IP地址和端口
• 检查网络连接（ping设备）
• 确保设备上正在运行Modbus TCP服务
• 检查防火墙规则

无效地址

• 验证设备支持的地址范围
• 检查是否使用基于0或基于1的寻址
• 有关有效的寄存器范围，请参阅设备文档

权限不足

• 某些寄存器可能是只读的
• 检查设备安全设置
• 验证设备上的用户权限

数据类型不匹配

• 确保数据类型与设备配置匹配
• 32位值需要2个连续的寄存器
• 使用适当的字节顺序（默认情况下为大端序）

技术细节

• 协议：Modbus TCP（IEEE标准）
• 默认端口: 502
• 运输：TCP/IP
• 支持的功能代码:

- FC1：读取线圈 - FC2：读取离散输入 - FC3：读取保持寄存器 - FC4：读取输入寄存器 - FC5：写入单线圈 - FC6：写入单个寄存器 - FC15：写入多个线圈 - FC16：写入多个寄存器 - FC43：读取设备标识（如果支持）

许可证

此MCP服务器按原样提供，用于工业Modbus TCP设备。

支持

对于问题或疑问：

1. 检查设备文档以了解支持的功能
2. 验证网络连接和设备配置
3. 使用 modbus_diagnostics 故障排除工具
4. 查看错误消息以获取具体指导

安全警告

⚠️ 小心：这个工具可以写工业设备。始终：

• 首先对非关键系统进行测试
• 了解寄存器写入的含义
• 使用适当的安全程序
• 查阅设备文档
• 遵循工业安全标准