modbus-mcp

Modbus MCP NPX Server

Overview
- NPX-friendly Model Context Protocol server exposing Modbus tools over stdio.
- Supports Modbus TCP, UDP, and Serial (RTU) via modbus-serial.
- Mirrors the Python Modbus MCP: core read/write, typed decode/encode, tag map, retries, chunking, and health.

Install/Run
- Run via npx (when published) or clone and build locally.

Local build
- From this folder:
- npm install
- npm run build
- node build/index.js

Claude Desktop config (example)
{
"mcpServers": {
"Modbus MCP (NPX)": {
"command": "modbus-mcp",
"env": { "MODBUS_TYPE": "tcp", "MODBUS_HOST": "127.0.0.1", "MODBUS_PORT": "502", "MODBUS_DEFAULT_SLAVE_ID": "1" }
}
}
}

Environment
- MODBUS_TYPE: tcp | udp | serial (default: tcp)
- MODBUS_HOST: host for TCP/UDP (default: 127.0.0.1)
- MODBUS_PORT: port for TCP/UDP (default: 502)
- MODBUS_DEFAULT_SLAVE_ID: default unit id (default: 1)
- MODBUS_SERIAL_PORT: serial device path (default: /dev/ttyUSB0)
- MODBUS_BAUDRATE: serial baud (default: 9600)
- MODBUS_PARITY: N | E | O (default: N)
- MODBUS_STOPBITS: stop bits (default: 1)
- MODBUS_BYTESIZE: data bits (default: 8)
- MODBUS_TIMEOUT: seconds per request (default: 1)
- MODBUS_MAX_RETRIES: retry attempts (default: 2)
- MODBUS_RETRY_BACKOFF_BASE: backoff seconds (default: 0.2)
- MODBUS_TOOL_TIMEOUT: per-tool timeout (seconds, optional)
- MODBUS_WRITES_ENABLED: true/false (default: true)
- REGISTER_MAP_FILE: path to tag-map JSON (optional)

Tools
- read_register: address, slave_id?
- write_register: address, value, slave_id?
- read_coils: address, count, slave_id?
- write_coil: address, value, slave_id?
- read_input_registers: address, count, slave_id?
- read_multiple_holding_registers: address, count, slave_id?
- read_discrete_inputs: address, count, slave_id?
- write_registers: address, values[], slave_id?
- write_coils_bulk: address, values[], slave_id?
- mask_write_register: address, and_mask, or_mask, slave_id?
- read_device_information: slave_id?, read_code?, object_id?
- read_holding_typed: address, dtype, count?, byteorder?, wordorder?, scale?, offset?, slave_id?
- read_input_typed: address, dtype, count?, byteorder?, wordorder?, scale?, offset?, slave_id?
- list_tags
- read_tag: name
- write_tag: name, value
- ping

Result shape
- Every tool returns JSON content: { success, data, error, meta }.

Tag map (optional)
- Example file referenced by REGISTER_MAP_FILE:
{
"PumpSpeed": { "table": "holding", "address": 100, "dtype": "float32", "count": 1, "byteorder": "big", "wordorder": "big", "slave_id": 1 },
"ValveOpen": { "table": "coil", "address": 5, "slave_id": 1 },
"Alarm": { "table": "discrete", "address": 10, "count": 4, "slave_id": 1 }
}

Notes
- Uses modbus-serial which supports TCP, UDP, and Serial (RTU). Function coverage: FC1, FC2, FC3, FC4, FC5, FC6, FC15, FC16, FC22, and MEI 43/14.
- Reads are chunked to protocol limits: coils/discretes=2000, registers=125.
- Typed decode/encode supports int16/uint16/int32/uint32/float32/int64/uint64/float64 with byteorder and wordorder semantics.