Modbus TCP/RTU Device

Modbus TCP/RTU Device — MCP Server

Let an AI agent read and control Modbus devices over Ethernet (Modbus TCP) or RS-485/RS-232 (Modbus RTU/ASCII): PID temperature controllers, recirculating chillers, PLCs, process sensors, VFDs and data loggers. You describe the device once in a register map (YAML or JSON). The agent then works with named points in real units, such as process_temperature = 37.2 °C or setpoint, instead of raw registers. The server enforces the map's rules: only writable points can be written by name, every writable number must have a min and max, and out-of-range values are refused before anything is sent. The map can also define a safe state, a list of point writes (heater off, controller to standby) that a SAFETY tool runs on request.

What this server adds over a plain register-poking Modbus MCP:

• Typed register maps: int16/uint16/int32/uint32/float32/float64/bool, word and byte order, scale and offset, units, enums (0 = standby, 1 = auto) and descriptions.
• Per-point limits: writable points need min/max or an enum, and values are checked before sending. Raw writes to addresses that belong to a mapped point are refused, so the limits can't be bypassed.
• Read-back: every write_point reads the value back and reports whether it matches.
• Safe state: an apply_safe_state SAFETY tool, defined in the map, that works even in --read-only mode.
• Read-only mode (--read-only), an audit log of every request and reply, and bounded request sizes.

Try it without hardware

uvx labmcp-modbus --simulate --check

The simulator is a generic single-loop PID temperature controller. Its layout is the bundled example register map. It is illustrative and not a copy of any vendor's map. A heater (3 °C/s at full power) heats a thermal mass that cools towards a 22 °C room (τ = 90 s). The PID loop has a ramping working setpoint and alarm bits. The simulator answers exception 02 for unimplemented addresses, 03 for values outside its own range (e.g. a 500 °C setpoint), and 0B for a wrong unit id. With --simulate --option register_map=my_map.yaml, points that are not in the example layout get zero-initialised storage, so you can test your own map.

Connect your device

1. Device setup: in the device's communications menu, enable Modbus and note its settings.

• RTU (RS-485): set the unit (slave) address (1–247), baud rate, parity and stop bits. The server defaults to the Modbus serial default of 19200 baud, 8 data bits, even parity, 1 stop bit. Many devices ship with other settings (e.g. 9600 8N1); put your device's settings in the address. Wire the USB-RS485 adapter's A/B (D−/D+) lines to the device; vendors disagree on the A/B labels, so swap them if nothing answers. Connect the signal ground, and put 120 Ω termination at both ends of longer buses.
• TCP: set the IP address. The port is 502 unless changed. Many TCP devices ignore the unit id. If yours does not, it is usually 1; the TCP implementation guide recommends 255 for directly addressed devices.

1. Write a register map for your device from its Modbus manual. Copy the example and see Register map below.
2. Test the connection:

   uvx labmcp-modbus --address tcp://192.168.1.20:502 --option register_map=~/maps/oven.yaml --check

uvx labmcp-modbus --address "serial:///dev/ttyUSB0?baudrate=9600&parity=N" --option unit_id=3 \ --option register_map=~/maps/controller.yaml --check uvx labmcp-modbus --address "serial://COM4?baudrate=19200&parity=E" --option register_map=C:/maps/chiller.json --check uvx labmcp-modbus --address "tcp://192.168.1.30:4001?framer=rtu" --check # RTU through a transparent gateway

   `--check` connects, reads the map's first point as a probe and prints `probe: ok: …` or the error. More address parameters: `stopbits=2`, `bytesize=7`, `framer=ascii` (Modbus ASCII), `timeout=1`, `retries=2`.

Register map

device:                 # optional

name: Incubator oven manufacturer: Example model: X-100 unit_id: 1 # --option unit_id overrides it word_order: big # default for 32/64-bit points byte_order: big

points: chamber_temperature: table: input # holding | input | coil | discrete address: 0 # 0-based protocol address ("30001" in the manual -> input 0) type: int16 # uint16 | int16 | uint32 | int32 | float32 | float64 | bool scale: 0.1 # value = raw * scale + offset unit: °C description: Chamber temperature setpoint: table: holding address: 0 # "40001" -> holding 0 type: int16 scale: 0.1 unit: °C writable: true min: 20 # required for writable numbers: checked before sending max: 60 mode: table: holding address: 1 writable: true enum: {0: standby, 1: run} heater_enable: table: coil address: 0 writable: true

safe_state: # optional: run in order by apply_safe_state

• {point: heater_enable, value: false}
• {point: mode, value: standby}

The server validates the map when it starts. Unknown fields (e.g. a misspelt maximum) and repeated keys (a second max, or a point defined twice) are errors rather than being silently ignored, so a typo can't remove a limit. Two writable points may not share a register (writing one would bypass the other's limits); read-only views of a writable register are fine. If the map is invalid, list_points shows the error and the device tools refuse to run. The server fails closed.

Add to your MCP client

Claude Code

claude mcp add oven -- uvx labmcp-modbus --address tcp://192.168.1.20:502 --option register_map=/home/me/maps/oven.yaml

Claude Desktop / Cursor / Windsurf (claude_desktop_config.json, .cursor/mcp.json, …)

{

"mcpServers": { "controller": { "command": "uvx", "args": [ "labmcp-modbus", "--address", "serial:///dev/ttyUSB0?baudrate=9600&parity=N", "--option", "unit_id=1", "--option", "register_map=/home/me/maps/controller.yaml", "--option", "raw_writes=false" ] } } }

Useful flags:

• --read-only allows reads only. apply_safe_state stays available.
• --option raw_writes=false removes write_register, write_registers and write_coil, so the agent can only write what the map allows. This is recommended once your map is complete.

Tools

get_connection_info, get_command_log and reconnect are built into every La