Modbus MCP

What kukapay/modbus-mcp MCP server does

The kukapay/modbus-mcp MCP server makes selected Modbus device operations available to MCP-compatible AI clients. It supports holding-register reads and writes, coil reads and writes, input-register reads, and multi-register holding-register reads. The server also provides an analyze_register prompt for interpreting register values with a customizable prompt.

This is suited to environments where an AI agent needs to inspect device state or issue supported Modbus commands through a client such as Claude Desktop. Write operations change device data, so deployments should be configured with the same access controls and operational safeguards used for other industrial control software.

How it works

The server uses connection settings from the process environment or a .env file, then communicates with a configured Modbus device. The connection mode is selected with MODBUS_TYPE, which accepts tcp, udp, or serial.

Tool calls use structured parameters such as an address, count, value, and slave ID. For example, a holding-register read identifies the register address and slave ID, while a coil read also specifies how many coils to retrieve. Clients that translate natural-language requests into tool calls may allow conversational use, but the README notes that this depends on the client. The MCP Inspector requires structured JSON input.

Setup and configuration

The project requires Python 3.10 or later and uses uv for dependency and virtual-environment management. The documented setup is:

1. Install uv.
2. Clone the repository.
3. Run uv sync from the repository directory.
4. Configure the server in the MCP client.

TCP and UDP connections use MODBUS_HOST, MODBUS_PORT, and the configured slave ID. Serial connections use MODBUS_SERIAL_PORT, MODBUS_BAUDRATE, MODBUS_PARITY, MODBUS_STOPBITS, MODBUS_BYTESIZE, and MODBUS_TIMEOUT. The documented defaults include localhost, port 502, slave ID 1, 9600 baud, no parity, one stop bit, eight data bits, and a one-second timeout. The configuration table names the slave-ID variable MODBUS_DEFAULT_SLAVE_ID, while the TCP example uses MODBUS_SLAVE_ID; verify the expected variable name in the project before deployment.

Claude Desktop can launch the server with uv, using the project directory and the modbus-mcp run target, while passing the Modbus environment variables in its server configuration.

Tools and capabilities

Supported operations include:

• read_register for one holding register.
• write_register for one holding register.
• read_coils for a range of coils.
• write_coil for one coil.
• read_input_registers for a range of input registers.
• read_multiple_holding_registers for a range of holding registers.
• analyze_register for analyzing register values through a customizable prompt.

The available transport choices are Modbus TCP, UDP, and serial. The material does not document additional protocol functions, device discovery, scheduling, authentication, or data persistence.

Limitations and notes

The README does not specify device-model compatibility, register schemas, retry behavior, concurrency guarantees, or safety validation for writes. Register addresses, counts, values, and slave IDs therefore need to match the target device’s Modbus documentation. Natural-language interaction is also client-dependent; structured tool input may be required.

The project is licensed under MIT. No paid API, external credential, or hosted service is described in the provided material.