kukapay/modbus-mcp

An MCP server that standardizes and contextualizes Modbus data, enabling seamless integration of AI agents with industrial IoT systems.
Features
- **Modbus Tools**:
- Read/write holding registers (read_register, write_register).
- Read/write coils (read_coils, write_coil).
- Read input registers (read_input_registers).
- Read multiple holding registers (read_multiple_holding_registers).
- **Prompt**: Analyze Modbus register values with a customizable prompt (analyze_register).
- **Flexible Connections**: Supports Modbus over TCP, UDP, or serial, configured via environment variables.
Requirements
- **Python**: 3.10
- **uv** for dependency and virtual environment management.
Installation
1. **Install uv**:
2. **Clone the Repository**:
3. **Install Dependencies**:
Configuration
The server connects to a Modbus device using parameters specified via environment variables. Set these variables in a .env file or your shell environment.
Environment Variables
| Variable | Description | Default | Required |
|------------------------- |--------------------------------------------------|----------------------|----------|
| MODBUS_TYPE | Connection type: tcp, udp, or serial | tcp | Yes |
| MODBUS_HOST | Host address for TCP/UDP | 127.0.0.1 | For TCP/UDP |
| MODBUS_PORT | Port for TCP/UDP | 502 | For TCP/UDP |
| MODBUS_DEFAULT_SLAVE_ID | Slave ID | 1 | For TCP/UDP |
| MODBUS_SERIAL_PORT | Serial port (e.g., /dev/ttyUSB0, COM1) | /dev/ttyUSB0 | For serial |
| MODBUS_BAUDRATE | Serial baud rate | 9600 | For serial |
| MODBUS_PARITY | Serial parity: N (none), E (even), O (odd) | N | For serial |
| MODBUS_STOPBITS | Serial stop bits | 1 | For serial |
| MODBUS_BYTESIZE | Serial byte size | 8 | For serial |
| MODBUS_TIMEOUT | Serial timeout (seconds) | 1 | For serial |
Example .env File
For TCP:
For Serial:
Usage
Installing for Claude Desktop
The configuration file:
Using Tools
**Note**: Natural language support depends on the client’s ability to parse and map prompts to tools. The MCP Inspector requires structured JSON, but the examples below show how conversational inputs translate.
1. **Read a Holding Register**:
- **Prompt**:
- **MCP Inspector JSON**:
- **Expected Output**: Value:
2. **Write to a Holding Register**:
- **Prompt**:
- **MCP Inspector JSON**:
- **Expected Output**: Successfully wrote 100 to register 10
3. **Read Coils**:
- **Prompt**: