modbus自动MCP服务器

Name: modbus自动MCP服务器
Author: dofliu

作者：dofliu2 星标更新：2025-10-20

安装使用来源：spider==github.com

项目介绍

Modbus TCP MCP 服务器

一个全面的模型上下文协议（MCP）服务器，用于与Modbus TCP设备进行交互。此服务器使大型语言模型能够连接到、读取和写入工业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  # 在Windows上：venv\Scripts\activate
pip install mcp pymodbus

使用方法

运行服务器

python modbus_tcp_mcp.py

该服务器作为基于标准I/O的MCP服务器运行，并等待来自MCP客户端的请求。

配置Claude Desktop

在你的Claude Desktop配置文件中添加以下内容：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%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 (float, 可选)：连接超时时间（秒，默认：10.0）
unit_id (int, 可选)：Modbus从机/单元ID（默认：1）

示例：

连接到位于192.168.1.50的PLC

2. modbus_read_registers

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

参数：

host (str)：设备IP地址
register_type (str)："holding"、"input"、"coil"或"discrete"
start_address (int)：起始寄存器地址（以0为基准）
count (int)：要读取的寄存器数量
data_type (str, 可选)："uint16"、"int16"、"uint32"、"int32"、"float32"、"bool"（默认："uint16"）
port (int, 可选)：TCP端口（默认：502）
unit_id (int, 可选)：从机ID（默认：1）
response_format (str, 可选)："markdown"或"json"（默认："markdown"）

示例：

从位于192.168.1.50的PLC读取保持寄存器100-105作为float32

3. modbus_write_register

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

参数：

host (str)：设备IP地址
address (int)：要写入的寄存器地址
value (int/float/bool)：要写入的值
register_type (str, 可选)："holding"或"coil"（默认："holding"）
data_type (str, 可选)：编码的数据类型（默认："uint16"）
port (int, 可选)：TCP端口（默认：502）
unit_id (int, 可选)：从机ID（默认：1）
response_format (str, 可选)："markdown"或"json"（默认："markdown"）

示例：

将1500写入位于192.168.1.50的PLC的保持寄存器100

4. modbus_write_multiple_registers

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

参数：

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

示例：

将值[100, 200, 300]写入位于192.168.1.50的设备的保持寄存器40-42

5. modbus_device_info

查询设备标识信息。

参数：

host (str)：设备IP地址
port (int, 可选)：TCP端口（默认：502）
unit_id (int, 可选)：从机ID（默认：1）
response_format (str, 可选)：输出格式（默认："markdown"）

示例：

从位于192.168.1.50的PLC获取设备信息

6. modbus_diagnostics

对设备执行诊断测试。

参数：

host (str)：设备IP地址
port (int, 可选)：TCP端口（默认：502）
unit_id (int, 可选)：从机ID（默认：1）
test_read (bool, 可选)：执行测试读取（默认：True）
response_format (str, 可选)：输出格式（默认："markdown"）

示例：

对位于192.168.1.50的Modbus设备执行诊断

7. modbus_disconnect

关闭与设备的连接。

参数：

host (str)：设备IP地址
port (int, 可选)：TCP端口（默认：502）

示例：

从位于192.168.1.50的PLC断开连接

寄存器类型

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

访问：读/写
大小：16位（2字节）
用途：通用数据存储、配置、设定点

输入寄存器（功能码4）

访问：只读
大小：16位（2字节）
用途：传感器读数、模拟输入、状态数据

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

访问：读/写
大小：1位（布尔值）
用途：数字输出、控制信号、二进制标志

离散输入（功能码2）

访问：只读
大小：1位（布尔值）
用途：数字输入、开关、二进制传感器

数据类型

类型	大小	范围	描述
`uint16`	1寄存器	0 到 65535	无符号16位整数
`int16`	1寄存器	-32768 到 32767	带符号16位整数
`uint32`	2寄存器	0 到 4294967295	无符号32位整数
`int32`	2寄存器	-2147483648 到 2147483647	带符号32位整数
`float32`	2寄存器	±3.4e±38	IEEE 754浮点数
`bool`	1寄存器/线圈	True/False	布尔值

地址

此服务器使用以0为基准的地址（协议地址）：

寄存器0 = 地址0
寄存器1 = 地址1
以此类推

如果你的设备文档使用了以1为基准的地址或偏移地址（例如，保持寄存器的40001-49999），减去偏移量：

保持寄存器40001 → 地址0
输入寄存器30001 → 地址0
线圈00001 → 地址0

示例

示例1：读取温度传感器

从位于192.168.1.50的设备读取输入寄存器100作为float32

示例2：控制继电器

将True写入位于192.168.1.50的设备的线圈5

示例3：读取多个值

从位于192.168.1.100的PLC读取保持寄存器0-9

示例4：写入配置

将值[1000, 2000, 3000, 4000, 5000]写入位于192.168.1.50的设备的保持寄存器200-204

示例5：设备诊断

对位于192.168.1.50的设备执行诊断，检查连通性和响应时间

错误处理

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

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

最佳实践

先测试连通性：在其他操作之前使用modbus_connect
使用适当的数据类型：匹配数据类型与设备配置
处理大量读取：如果需要，分批读取寄存器（最大125个寄存器）
关闭连接：完成操作后使用modbus_disconnect释放资源
运行诊断：使用modbus_diagnostics工具进行故障排除

故障排除

连接超时

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

地址无效

验证设备支持的地址范围
检查是否使用了以0为基准或以1为基准的地址
查阅设备文档以获取有效的寄存器范围

权限被拒绝

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

数据类型不匹配

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

技术细节

协议：Modbus TCP（IEEE标准）
默认端口：502
传输：TCP/IP
支持的功能码：
- FC1：读取线圈
- FC2：读取离散输入
- FC3：读取保持寄存器
- FC4：读取输入寄存器
- FC5：写入单个线圈
- FC6：写入单个寄存器
- FC15：写入多个线圈
- FC16：写入多个寄存器
- FC43：读取设备标识（如果支持）

许可

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

支持

对于问题或疑问：

查阅设备文档以确认支持的功能
验证网络连通性和设备配置
使用modbus_diagnostics工具进行故障排除
查阅错误消息以获得具体指导

安全警告

⚠️ 注意：此工具可以写入工业设备。始终：

先在非关键系统上测试
了解寄存器写入的影响
使用正确的安全程序
查阅设备文档
遵循工业安全标准