Modbus MCP Server
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).
- Read/write 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
-
Install
uv:curl -LsSf https://astral.sh/uv/install.sh | sh
-
Clone the Repository:
git clone https://github.com/kukapay/modbus-mcp.git cd modbus-mcp
-
Install Dependencies:
uv sync
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:
MODBUS_TYPE=tcp
MODBUS_HOST=192.168.1.100
MODBUS_PORT=502
MODBUS_SLAVE_ID=1
For Serial:
MODBUS_TYPE=serial
MODBUS_SERIAL_PORT=/dev/ttyUSB0
MODBUS_BAUDRATE=9600
MODBUS_PARITY=N
MODBUS_STOPBITS=1
MODBUS_BYTESIZE=8
MODBUS_TIMEOUT=1
Usage
Installing for Claude Desktop
The configuration file:
{
"mcpServers": {
"Modbus MCP Server": {
"command": "uv",
"args": [ "--directory", "/path/to/modbus-mcp", "run", "modbus-mcp" ],
"env": { "MODBUS_TYPE": "tcp", "MODBUS_HOST": "127.0.0.1", "MODBUS_PORT": 502 },
}
}
}
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.
-
Read a Holding Register:
- Prompt:
Please read the value of Modbus holding register 0. - MCP Inspector JSON:
{ "tool": "read_register", "parameters": {"address": 0, "slave_id": 1} }
- Expected Output:
Value: <register_value>
- Prompt:
-
Write to a Holding Register:
- Prompt:
Set Modbus holding register 10 to the value 100. - MCP Inspector JSON:
{ "tool": "write_register", "parameters": {"address": 10, "value": 100, "slave_id": 1} }
- Expected Output:
Successfully wrote 100 to register 10
- Prompt:
-
Read Coils:
- Prompt:
Check the status of the first 5 Modbus coils starting at address 0. - MCP Inspector JSON:
{ "tool": "read_coils", "parameters": {"address": 0, "count": 5, "slave_id": 1} }
- Expected Output:
Coils 0 to 4: [False, False, False, False, False]
- Prompt:
-
Write to a Coil:
- Prompt:
Turn on Modbus coil 5. - MCP Inspector JSON:
{ "tool": "write_coil", "parameters": {"address": 5, "value": true, "slave_id": 1} }
- Expected Output:
Successfully wrote True to coil 5
- Prompt:
-
Read Input Registers:
- Prompt:
Read the values of 3 Modbus input registers starting from address 2. - MCP Inspector JSON:
{ "tool": "read_input_registers", "parameters": {"address": 2, "count": 3, "slave_id": 1} }
- Expected Output:
Input Registers 2 to 4: [<value1>, <value2>, <value3>]
- Prompt:
-
Read Multiple Holding Registers:
- Prompt:
Get the values of Modbus holding registers 0 through 2. - MCP Inspector JSON:
{ "tool": "read_multiple_holding_registers", "parameters": {"address": 0, "count": 3, "slave_id": 1} }
- Expected Output:
Holding Registers 0 to 2: [<value1>, <value2>, <value3>]
- Prompt:
License
This project is licensed under the MIT License. See LICENSE for details.
Metadata
Release files for iflow-mcp_kukapay_modbus-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_kukapay_modbus_mcp-0.1.0.tar.gz | 20.0 kB | Without provenance | Details for iflow_mcp_kukapay_modbus_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_kukapay_modbus_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_kukapay_modbus_mcp-0.1.0-py3-none-any.whl |
Total release size: 26.7 kB
Release files / iflow_mcp_kukapay_modbus_mcp-0.1.0.tar.gz
| Download URL | iflow_mcp_kukapay_modbus_mcp-0.1.0.tar.gz |
|---|---|
| Size | 20.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0479008a2981e952d24b9a46745d830a9f356d3c3b805b79c8db83a28cb9efe2
|
|
BLAKE2b-256 checksum How to use checksums |
635641735072c8b41cce48c6ca840ed0960a016868a954f0df91b3850c4d1f9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_kukapay_modbus_mcp-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_kukapay_modbus_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 6.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
137289c6915305807f26a7177ee405f8abaa5b40ba095c5bbd2bafb0847bae31
|
|
BLAKE2b-256 checksum How to use checksums |
0e5b49ee00ea592b5e4e8ad20b1936e409c9d7c9b323a600876c7710f2ba8ea1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_kukapay_modbus-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.