HelloWorld
登录
k

kukapay

home-automation-and-iotagent-orchestration

278 查看 · 2026-07-07 更新

Modbus MCP 服务器

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

GitHub License Python Version 状态

特性

  • 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: bash curl -LsSf https://astral.sh/uv/install.sh | sh

  2. 克隆仓库: bash git clone https://github.com/kukapay/modbus-mcp.git cd modbus-mcp

  3. 安装依赖: bash uv sync

配置

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

环境变量

变量描述默认值是否必需
MODBUS_TYPE连接类型: tcp, udp, 或 serialtcp是
MODBUS_HOSTTCP/UDP 的主机地址127.0.0.1对于 TCP/UDP
MODBUS_PORTTCP/UDP 的端口502对于 TCP/UDP
MODBUS_DEFAULT_SLAVE_ID从站 ID1对于 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 桌面版安装

配置文件:

json { "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. 读取保持寄存器:

    • 提示:

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

    • MCP Inspector JSON: json { "tool": "read_register", "parameters": {"address": 0, "slave_id": 1} }- 预期输出: Value: <register_value>

  2. 写入保持寄存器:

    • 提示:

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

    • MCP Inspector JSON: json { "tool": "write_register", "parameters": {"address": 10, "value": 100, "slave_id": 1} }

    • 预期输出: 成功将100写入寄存器10

  3. 读取线圈状态:

    • 提示:

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

    • MCP Inspector JSON: json { "tool": "read_coils", "parameters": {"address": 0, "count": 5, "slave_id": 1} }

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

  4. 写入线圈:

    • 提示:

      打开Modbus线圈5。

    • MCP Inspector JSON: json { "tool": "write_coil", "parameters": {"address": 5, "value": true, "slave_id": 1} }

    • 预期输出: 成功将True写入线圈5

  5. 读取输入寄存器:

    • 提示:

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

    • MCP Inspector JSON: json { "tool": "read_input_registers", "parameters": {"address": 2, "count": 3, "slave_id": 1} }

    • 预期输出: 输入寄存器2到4: [<value1>, <value2>, <value3>]

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

    • 提示:

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

    • MCP Inspector JSON: json { "tool": "read_multiple_holding_registers", "parameters": {"address": 0, "count": 3, "slave_id": 1} }

    • 预期输出: 保持寄存器0至2: [<value1>, <value2>, <value3>]

许可证

本项目采用MIT许可证。详情请参见LICENSE。

来源