Modbus MCP Server

Modbus MCP 服务

一个对 Modbus 数据进行标准化和上下文处理的 MCP 服务，可实现 AI Agent 与工业物联网系统的无缝集成。

功能特性

• 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 Server": {
           "command": "uv",
           "args": [ "--directory", "/path/to/modbus-mcp", "run", "modbus-mcp" ],
           "env": { "MODBUS_TYPE": "tcp", "MODBUS_HOST": "127.0.0.1", "MODBUS_PORT": 502 },
       }
   }
}

使用工具

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

1. 读取保持寄存器：

   • 提示词：

     Please read the value of Modbus holding register 0.
     

   • MCP Inspector JSON：

     {
       "tool": "read_register",
       "parameters": {"address": 0, "slave_id": 1}
     }
     

   • 预期输出：Value: <register_value>

2. 写入保持寄存器：

   • 提示词：

     Set Modbus holding register 10 to the value 100.
     

   • MCP Inspector JSON：

     {
       "tool": "write_register",
       "parameters": {"address": 10, "value": 100, "slave_id": 1}
     }
     

   • 预期输出：Successfully wrote 100 to register 10

3. 读取线圈：

   • 提示词：

     Check the status of the first 5 Modbus coils starting at address 0.
     

   • MCP Inspector JSON：

     {
       "tool": "read_coils",
       "parameters": {"address": 0, "count": 5, "slave_id": 1}
     }
     

   • 预期输出：Coils 0 to 4: [False, False, False, False, False]

4. 写入线圈：

   • 提示词：

     Turn on Modbus coil 5.
     

   • MCP Inspector JSON：

     {
       "tool": "write_coil",
       "parameters": {"address": 5, "value": true, "slave_id": 1}
     }
     

   • 预期输出：Successfully wrote True to coil 5

5. 读取输入寄存器：

   • 提示词：

     Read the values of 3 Modbus input registers starting from address 2.
     

   • MCP Inspector JSON：

     {
       "tool": "read_input_registers",
       "parameters": {"address": 2, "count": 3, "slave_id": 1}
     }
     

   • 预期输出：Input Registers 2 to 4: [<value1>, <value2>, <value3>]

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

   • 提示词：

     Get the values of Modbus holding registers 0 through 2.
     

   • MCP Inspector JSON：

     {
       "tool": "read_multiple_holding_registers",
       "parameters": {"address": 0, "count": 3, "slave_id": 1}
     }
     

   • 预期输出：Holding Registers 0 to 2: [<value1>, <value2>, <value3>]

许可证

本项目采用 MIT 许可证授权。详情请参阅 LICENSE。