modbus-connector-mcp

MCP server that gives LLM agents (Claude Desktop, CLI agents) access to Modbus devices through the Modbus Connector backends: reading and writing registers, unit/address scanners, and long-running jobs — device simulator, gateway, RTU sniffer and polling.

No Qt, no GUI — the only dependencies are modbus-connector (pymodbus-only base) and the official mcp SDK.

Installation

pip install modbus-connector-mcp

Standalone binaries (modbus-connector-mcp-macos / -linux / -windows.exe, no Python needed) are attached to Releases.

Running with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "modbus": {
      "command": "modbus-connector-mcp",
      "args": []
    }
  }
}

Start the server with --read-only to forbid all writes (modbus_write and the simulate/gateway jobs are rejected; reads, scanners, sniff/poll jobs keep working).

The server speaks stdio (JSON-RPC 2.0) and exits when the client disconnects — all running jobs stop with it.

Connection specs

Every tool takes a conn (or listen/target) spec string:

  • tcp:192.168.1.10:502 — Modbus TCP (default port 502)
  • rtu:/dev/ttyUSB0,baud=9600,bits=8,parity=N,stop=1 — Modbus RTU serial
  • rtuovertcp:192.168.1.10:502 — RTU framing over TCP (also rtu-over-tcp:), rtuoverudp:...

Tools

Tool What it does
modbus_read One-shot read of coils/discrete_inputs/holding/input registers, decoded values (format/order/scale/offset)
modbus_write Write coils/holding registers
modbus_scan_units Scan a unit-id range
modbus_scan_addresses Scan a register address range of one unit
templates_list / templates_get Bundled device templates catalog
job_start / job_stop / job_list / job_status / job_events Long-running jobs (see below)

Jobs

job_start(kind, params) returns immediately with a job_id; the process keeps running inside the server:

  • simulate — {"listen": "tcp:1502", "unit": 1|null, "map": {"registers": [...]}} (map = template/session JSON register list; master writes become events)
  • gateway — {"listen": "tcp:5020", "target": "rtu:/dev/ttyUSB0,baud=9600", "units": [1,5]|null}
  • sniff — {"port": "/dev/cu.usbserial", "baud": 19200, ...} (passive RTU listening)
  • poll — {"conn": "tcp:...", "unit": 1, "kind": "holding_registers", "address": 0, "count": 2, "interval_ms": 1000}

job_events(job_id, since_seq, limit) returns up to limit events newer than since_seq plus a next_seq cursor for the next call — poll it incrementally to follow the traffic.

Port conflicts

The server does not share devices with the GUI or CLI: a serial port or a TCP listen port can be opened by one process only. If a job fails with "port busy", close the other session using it.

Development

pip install -e mcp           # into the repo's dev venv
.venv/bin/python -m pytest mcp/tests -q

Project links

Data verified by PyPI on Aug 31, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for cramen from gravatar.com cramen

Credits

Author: cramen

GitHub Statistics

Data verified by PyPI on Aug 31, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT

Requires

Python >=3.11

Tags

modbus mcp model-context-protocol modbus-tcp modbus-rtu

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

modbus_connector_mcp-0.1.1.tar.gz (15.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

modbus_connector_mcp-0.1.1-py3-none-any.whl (11.4 kB view details)

Uploaded Python 3

File details

Details for the file modbus_connector_mcp-0.1.1.tar.gz.

File metadata

  • Download URL: modbus_connector_mcp-0.1.1.tar.gz
  • Upload date:
  • Size: 15.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for modbus_connector_mcp-0.1.1.tar.gz
Algorithm Hash digest
SHA256 f7a63ba72c8751cfaed457f9258fccbea5e13f632f37107c8ad557bb918c9e72
MD5 e43504da91592ac91372f8efc91b8eae
BLAKE2b-256 2f90cf7b5710f00b0dd7ad7432a7d1ab7b137268f5e363df392b6ce50b4ff4c8

See more details on using hashes here.

Provenance

The following attestation bundles were made for modbus_connector_mcp-0.1.1.tar.gz:

Publisher: build.yml on cramen/modbus_connector

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file modbus_connector_mcp-0.1.1-py3-none-any.whl.

File metadata

File hashes

Hashes for modbus_connector_mcp-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 0a7a0c37a96d00c49d5adb171e3ebf9081dd3b40d876beda0737e721ab8094ad
MD5 b75439abcfeab3a996c3f1e22acca24b
BLAKE2b-256 82e7b3f3a1b64f63073e9c548af338e57cb510844a33589121ddba10f8f57aae

See more details on using hashes here.

Provenance

The following attestation bundles were made for modbus_connector_mcp-0.1.1-py3-none-any.whl:

Publisher: build.yml on cramen/modbus_connector

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page