Modbus Mcp

Modbus MCP 服务

一个轻量级的 Model Context Protocol (MCP) 服务，可通过安全、标准化的方式将大模型 Agent 连接到 Modbus 设备，实现 AI 驱动的工作流与楼宇自动化（BAS）和工业控制（ICS）系统的无缝集成，让 Agent 能够监控实时传感器数据、控制设备并编排复杂的自动化任务。

快速开始

使用 uv 将 Modbus MCP 服务作为依赖项添加到项目中并进行管理，也可以通过 uv pip install 或 pip install 直接安装。有关完整的安装说明和更多详情，请参阅文档的安装部分。

uv add modbus-mcp

此服务可以嵌入应用程序并直接从中运行。默认情况下，它会在 http://127.0.0.1:8000/mcp/ 提供 Streamable HTTP 端点。

# app.py
from modbus_mcp import ModbusMCP

mcp = ModbusMCP()

if __name__ == "__main__":
    mcp.run(transport="http")

也可以使用提供的 CLI 从命令行启动，无需修改源代码。

modbus-mcp

或者在临时、隔离的环境中使用 uvx 启动。有关详情，请参阅使用工具指南。

uvx modbus-mcp

配置

对于大多数操作都针对特定设备的用例（例如可编程逻辑控制器（PLC）或 Modbus 网关），可以在运行时通过环境变量指定设备的连接设置（host、port 和 unit），这样，所有省略显式连接参数的提示词都会路由到该设备。

export MODBUS_MCP_MODBUS__HOST=10.0.0.1
export MODBUS_MCP_MODBUS__PORT=502
export MODBUS_MCP_MODBUS__UNIT=1

也可以在工作目录中的 .env 文件内指定这些设置。

# .env
modbus_mcp_modbus__host=10.0.0.1
modbus_mcp_modbus__port=502
modbus_mcp_modbus__unit=1

与多台设备交互时，可以在工作目录中的 devices.json 文件内为每台设备定义唯一的 name，并设置其连接参数（host、port、unit）。之后，提示词便可通过 name 引用设备。

{
  "devices": [
    {"name": "Boiler", "host": "10.0.0.3", "port": 503, "unit": 3},
    {"name": "Valve", "host": "10.0.0.4", "port": 504, "unit": 4}
  ]
}

MCP Inspector

要确认服务已启动并运行，并探索可用的资源和工具，请运行 MCP Inspector，并将其连接到 http://127.0.0.1:8000/mcp/ 上的 Modbus MCP 服务。请确保将传输方式设为 Streamable HTTP。

npx @modelcontextprotocol/inspector

核心概念

Modbus MCP 服务基于 FastMCP 构建，并利用其核心构建模块——资源模板、工具和提示词，以简洁、符合 Python 风格的接口，精简 Modbus 读写操作并最大限度减少样板代码。

读取寄存器

设备上的每个寄存器都映射为一个资源（并作为工具公开），并使用资源模板指定连接详情（host、port、unit）和读取参数（address、count）。

@mcp.resource("tcp://{host}:{port}/{address}?count={count}&unit={unit}")
@mcp.tool(
    annotations={"title": "Read Registers", "readOnlyHint": True, "openWorldHint": True}
)
async def read_registers(
    host: str = settings.modbus.host,
    port: int = settings.modbus.port,
    address: int = 40001,
    count: int = 1,
    unit: int = settings.modbus.unit,
) -> int | list[int]:
    """Reads the contents of one or more registers on a remote unit."""
    ...

写入寄存器

写操作通过一个工具公开，接受相同的连接详情（host、port、unit），并允许在一次原子调用中设置一个或多个 holding registers 或 coils 的内容。

@mcp.tool(
    annotations={
        "title": "Write Registers",
        "readOnlyHint": False,
        "openWorldHint": True,
    }
)
async def write_registers(
    data: list[int],
    host: str = settings.modbus.host,
    port: int = settings.modbus.port,
    address: int = 40001,
    unit: int = settings.modbus.unit,
) -> str:
    """Writes data to one or more registers on a remote unit."""
    ...

身份验证

要在 Streamable HTTP 传输方式下使用内置的 AuthKit 提供程序启用身份验证，请在 .env 文件中提供 AuthKit 域名和重定向 URL。有关详情，请参阅 AuthKit 提供程序部分。

交互式提示词

结构化响应消息通过提示词实现，可用于引导交互、明确缺失的参数，并妥善处理错误。

@mcp.prompt(name="modbus_help", tags={"modbus", "help"})
def modbus_help() -> list[Message]:
    """Provides examples of how to use the Modbus MCP server."""
    ...

以下是一些可用于与服务交互的文本输入示例。

Please read the value of register 40001 on 127.0.0.1:502.
Set register 40005 to 123 on host 192.168.1.10, unit 3.
Write [1, 2, 3] to holding registers starting at address 40010.
What is the status of input register 30010 on 10.0.0.5?

示例

examples 文件夹包含示例项目，展示如何使用各种客户端 API 与 Modbus MCP 服务集成，为大模型提供工具和上下文。

• openai-agents - 展示如何使用 OpenAI Agents SDK 连接到 Modbus MCP 服务。
• openai - 一个利用 OpenAI Python library 中远程 MCP 服务支持的精简应用。
• pydantic-ai - 展示如何使用 PydanticAI Agent Framework 连接到 Modbus MCP 服务。

Docker

Modbus MCP 服务可以按如下方式部署为 Docker 容器：

docker run -d \
  --name modbus-mcp \
  --restart=always \
  -p 8080:8000 \
  --env-file .env \
  ghcr.io/ezhuk/modbus-mcp:latest

此配置会将主机上的 8080 端口映射到容器内 MCP 服务的 8000 端口，并在 .env 文件存在时从中加载设置。

许可证

此服务采用 MIT License 授权。