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.
2. Write a register map for your device from its Modbus manual. Copy the example and see Register map below.
3. Test the connection:
   bash

   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 LabMCP server. apply_safe_state is listed only when the register map defines a safe_state.

Safety limits

This server has no global --limit values: a generic Modbus client can't know what a register means. The protections come from the register map and the server:

Example prompts

• "What's the chamber temperature and output power right now? Show every point with its unit."
• "Ramp the controller to 55 °C at 2 °C/min, switch it to auto, enable the heater, and tell me when it's within 0.5 °C of setpoint."
• "Set the high alarm to 70 °C, then check whether any alarm or sensor-fault bits are active."
• "Read holding registers 100–109 and decode them as float32 (try both word orders). I'm mapping a new chiller."
• "Something's wrong: put the controller in its safe state and confirm the heater is off."

Notes

• Addresses are 0-based on the wire. Manuals often use 1-based "Modicon" numbers (40001 = holding 0). If every read is off by one register, the map uses the wrong convention.
• Word order is not standardised for 32-bit values: the Modbus spec only defines byte order within a register. If a float or 32-bit value looks absurd, try word_order: little. read_registers with decode_as helps you find the right order.
• A float point that reads NaN or infinity (many devices use NaN as "no value", e.g. a sensor fault) comes back with value: null and an error; read_registers with decode_as shows it as "nan"/"inf".
• write_point uses FC06 for single-register points, FC16 for multi-register points and FC05 for coils. A few devices accept only FC16 even for single registers. For those, map the value as part of a multi-register point or report it so we can add an option.
• Some controllers save written parameters to non-volatile memory, which survives only a limited number of write cycles. Don't have the agent rewrite setpoints in a tight loop. Check whether the manual offers a RAM-only or remote setpoint register.
• Reading is normally side-effect free, but a few devices clear counters or alarms when they are read. Leave such registers out of the map or mark them in description.
• Modbus TCP devices often accept only a few simultaneous connections. Close other SCADA or logging clients if the connection is refused.
• Timeouts nearly always mean a wrong unit id, baud rate, parity or A/B wiring. Exception 02 means an address the device does not implement. Exception 03 means the device rejected the value by its own internal limits.
• Works with pymodbus 3.8 or newer (the unit keyword changed from slave= to device_id= in 3.10; both are handled).
• The bundled map is an illustrative example. Contributions of real device maps are welcome: include the manual title and revision the addresses came from.

Hardware verification