Modbus MCP 服务器

一个标准化并上下文化 Modbus 数据的 MCP 服务器，使 AI 代理能够无缝集成到工业物联网系统中。

特性

• Modbus 工具：
  • 读写保持寄存器（read_register，write_register）。
  • 读写线圈（read_coils，write_coil）。
  • 读输入寄存器（read_input_registers）。
  • 读多个保持寄存器（read_multiple_holding_registers）。
• 提示：使用可定制的提示分析 Modbus 寄存器值（analyze_register）。
• 灵活连接：支持通过 TCP、UDP 或串行连接的 Modbus，可通过环境变量配置。

要求

• Python：3.10
• uv 用于依赖管理和虚拟环境管理。

安装

1. 安装 uv：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. 克隆仓库：

   git clone https://github.com/kukapay/modbus-mcp.git
   cd modbus-mcp
   

3. 安装依赖项：

   uv sync
   

配置

服务器通过环境变量指定的参数连接到 Modbus 设备。可以在 .env 文件或您的 shell 环境中设置这些变量。

环境变量

变量	描述	默认值	必需
MODBUS_TYPE	连接类型：tcp，udp，或 serial	tcp	是
MODBUS_HOST	TCP/UDP 的主机地址	127.0.0.1	对于 TCP/UDP
MODBUS_PORT	TCP/UDP 的端口	502	对于 TCP/UDP
MODBUS_DEFAULT_SLAVE_ID	从设备ID	1	对于 TCP/UDP
MODBUS_SERIAL_PORT	串行端口（例如，/dev/ttyUSB0，COM1）	/dev/ttyUSB0	对于串行
MODBUS_BAUDRATE	串行波特率	9600	对于串行
MODBUS_PARITY	串行校验位：N（无），E（偶），O（奇）	N	对于串行
MODBUS_STOPBITS	串行停止位	1	对于串行
MODBUS_BYTESIZE	串行字节大小	8	对于串行
MODBUS_TIMEOUT	串行超时（秒）	1	对于串行

示例 .env 文件

对于 TCP：

MODBUS_TYPE=tcp
MODBUS_HOST=192.168.1.100
MODBUS_PORT=502
MODBUS_SLAVE_ID=1

对于串行：

MODBUS_TYPE=serial
MODBUS_SERIAL_PORT=/dev/ttyUSB0
MODBUS_BAUDRATE=9600
MODBUS_PARITY=N
MODBUS_STOPBITS=1
MODBUS_BYTESIZE=8
MODBUS_TIMEOUT=1

使用方法

在 Claude Desktop 上安装

配置文件：

{
   "mcpServers": {
       "Modbus MCP 服务器": {
           "命令": "uv",
           "参数": ["--directory", "/path/to/modbus-mcp", "run", "modbus-mcp"],
           "环境": { "MODBUS_TYPE": "tcp", "MODBUS_HOST": "127.0.0.1", "MODBUS_PORT": 502 },
       }
   }
}

使用工具

注意：自然语言支持取决于客户端解析和映射提示到工具的能力。MCP Inspector 需要结构化的 JSON，但下面的例子展示了如何将对话输入转换为 JSON。

1. 读取保持寄存器：

   • 提示：

     请读取 Modbus 保持寄存器 0 的值。
     

   • MCP Inspector JSON：

     {
       "工具": "read_register",
       "参数": {"地址": 0, "从设备ID": 1}
     }
     

   • 预期输出：值: <寄存器值>

2. 写入保持寄存器：

   • 提示：

     将 Modbus 保持寄存器 10 设置为值 100。
     

   • MCP Inspector JSON：

     {
       "工具": "write_register",
       "参数": {"地址": 10, "值": 100, "从设备ID": 1}
     }
     

   • 预期输出：成功写入 100 到寄存器 10

3. 读取线圈：

   • 提示：

     检查从地址 0 开始的前 5 个 Modbus 线圈的状态。
     

   • MCP Inspector JSON：

     {
       "工具": "read_coils",
       "参数": {"地址": 0, "数量": 5, "从设备ID": 1}
     }
     

   • 预期输出：线圈 0 到 4: [False, False, False, False, False]

4. 写入线圈：

   • 提示：

     打开 Modbus 线圈 5。
     

   • MCP Inspector JSON：

     {
       "工具": "write_coil",
       "参数": {"地址": 5, "值": true, "从设备ID": 1}
     }
     

   • 预期输出：成功写入 True 到线圈 5

5. 读取输入寄存器：

   • 提示：

     从地址 2 开始读取 3 个 Modbus 输入寄存器的值。
     

   • MCP Inspector JSON：

     {
       "工具": "read_input_registers",
       "参数": {"地址": 2, "数量": 3, "从设备ID": 1}
     }
     

   • 预期输出：输入寄存器 2 到 4: [<值1>, <值2>, <值3>]

6. 读取多个保持寄存器：

   • 提示：

     获取 Modbus 保持寄存器 0 到 2 的值。
     

   • MCP Inspector JSON：

     {
       "工具": "read_multiple_holding_registers",
       "参数": {"地址": 0, "数量": 3, "从设备ID": 1}
     }
     

   • 预期输出：保持寄存器 0 到 2: [<值1>, <值2>, <值3>]

许可证

本项目根据 MIT 许可证发布。详情见 LICENSE。