0.3.0 package and tool migration: Install industriagents-profibus-mcp from npm (requires uv) or PyPI; the command remains profibus-mcp. The advertised catalog now contains 7 tools. Older tool names in the examples below remain compatibility calls. See the architecture and canonical tool guide and release guide.

profibus-python

Python MCP server for PROFIBUS DP. Built with uv, mcp[cli] (1.22 or later, below 2) and anyio, it exposes the profibus-mcp CLI with tools for AI agents and MCP-compatible clients to scan the bus, exchange cyclic data, read diagnostics and parse GSD files. PROFIBUS PA is a goal, not supported yet.

Two backends exist. mock talks to profibus-mock-slave over TCP and works for every tool. serial (the default) stands for a DP master on an RS-485 adapter and is not implemented: bus tools return success: false and the port is never opened. See Status in the repository README.

Requirements

• Python 3.11+
• uv
• For the mock backend: profibus-mock-slave running (see its README)

Quick start

From the repository root, with the mock slave already running on 127.0.0.1:7100:

cd profibus-python
uv sync
PROFIBUS_BACKEND=mock uv run profibus-mcp

The server speaks MCP over stdio, so it waits for a client on stdin; stop it with Ctrl-C. The repository README shows how to start the mock and run the server under the MCP Inspector.

Configuration

Settings are environment variables, for example in your MCP client's env block. They are read once at startup, after the .env file (see below) is loaded; an unusable value (say PROFIBUS_BAUDRATE=fast) stops the server with a one-line error on stderr and exit code 2.

Booleans accept true/false, yes/no, on/off and 1/0; anything else is a startup error rather than a silent false.

Changed from the scaffold:

• PROFIBUS_MOCK=true and PROFIBUS_PORT=mock used to serve invented data in-process. They are deprecated aliases for PROFIBUS_BACKEND=mock now (a warning is logged), so the mock slave has to be running.
• PROFIBUS_CONFIG_CMDS_ENABLED is gone; no tool used it. Setting it logs a warning.
• .env is no longer read from the working directory; only profibus-python/.env, and only for this server's own settings. See below.
• With PROFIBUS_GSD_PATH set, load_gsd_file no longer opens paths outside it.

.env and --env-file

The server reads one .env by itself: profibus-python/.env of a source checkout, found relative to the package source. It never reads a .env from the working directory or any parent directory, and an installed package (in site-packages) reads none at all. A server started by an MCP client may run in the client's project directory, which may not be trusted, and settings such as the mock endpoint or the slave map decide where a write goes. .env.example lists every setting.

From that file, only this server's own settings are applied: PROFIBUS_* variables and SLAVE_MAP_FILE. Names are compared upper-cased (as Windows does), so profibus_backend=mock and export PROFIBUS_BACKEND=mock work. Everything else is ignored with a warning on stderr naming the variable:

• safety switches such as PROFIBUS_WRITES_ENABLED, in any spelling (profibus_writes_enabled, export Profibus_Writes_Enabled=...);
• variables of other programs (PATH, LD_PRELOAD, PYTHONPATH, ...).

Variables already set in the environment win over the file. Enable writes in the process environment (the MCP client's env block), or in a file you name explicitly:

uv run profibus-mcp --env-file /path/to/bench.env

--env-file replaces profibus-python/.env (only the named file is read) and may set every variable. profibus-mcp --version prints the version.

Responses

Every tool returns { "success": bool, "data": ..., "error": str | null, "meta": {...} }. Bus tools put the backend in meta.backend (mock or serial), plus operation, duration_ms and, for the mock, endpoint and attempts. Invalid arguments come back as success: false with an Invalid arguments: ... error and meta.backend. Addresses, lengths and byte values are strict integers: "5", 5.0 and true are refused.

Write tools also report meta.outcome and meta.request_sent:

A write is never sent twice: only a connection that could not be made is retried. When the MCP client disconnects (its stdin closes), pending requests are cancelled: one that has not been sent yet ends as not_sent and is never sent, and the server exits with status 0.

Layout

profibus-python/
├── README.md
├── pyproject.toml
├── uv.lock
├── .python-version
├── .env.example        # every setting, with the .env safety rule
├── src/profibus_mcp
│   ├── __init__.py
│   ├── cli.py          # entry point: .env, config, logging to stderr
│   ├── config.py       # all settings, read at startup
│   ├── server.py       # FastMCP wiring, argument errors as envelopes
│   ├── tools.py        # compatibility exports
│   ├── protocol/       # 7 advertised tools and legacy dispatch
│   ├── application/    # protocol operations
│   ├── domain/         # ports, errors and policy
│   ├── infrastructure/ # alias maps and audit
│   ├── adapters/       # native master and backend implementations
│   ├── pb_master.py    # compatibility import for the master adapter
│   └── gsd_parser.py   # GSD keyword-file parser
└── tests/              # pytest: unit tests and stdio tests against the mock

CONTRIBUTING.md describes how to run the checks and work on the code.