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

profinet-python

Python MCP server for PROFINET IO networks. Built with uv, mcp[cli], scapy and lxml, it exposes the profinet-mcp CLI for AI agents and MCP clients. Which tools work depends on the backend; see Status in the repository README.

Requirements

• Python 3.11+
• uv
• For PROFINET_BACKEND=mock: the mock IO device
• For PROFINET_BACKEND=network: an Ethernet interface on the PROFINET network and raw-socket privileges on it (root or CAP_NET_RAW on Linux, /dev/bpf* access on macOS)

Quick start

From the repository root:

uv sync --directory profinet-python
PROFINET_BACKEND=mock uv run --directory profinet-python profinet-mcp      # against the mock
uv run --directory profinet-python profinet-mcp --help                     # options and settings

The server speaks MCP over stdio, so it waits for a client on stdin; see the repository README for an MCP client configuration. Only JSON-RPC goes to stdout; logs go to stderr.

Backends

meta.backend in each envelope names the backend that answered.

Tools that change a device (write_io_data, write_device_by_alias, set_device_name, set_device_ip, identify_device) also report meta.outcome and meta.request_sent:

Connecting to the mock is retried (PROFINET_MAX_RETRIES); a read whose reply is lost is sent again, but a write or DCP command never is. "rejected" is used only when the mock marks a refusal "rejected": true (refused before anything changed); any other failure after a send is "unknown".

Every tool call has one absolute deadline, fixed when the call starts (all connect and reply timeouts, retries and backoff, plus slack: 45.5 s with the defaults) and shared by every request the call makes; it is never restarted per request. Waiting to reach a busy device counts against it, and the deadline is checked again right before each send, so a change is never sent after it: a request that never left is not_sent, a change that did is unknown. There is no lock or queue in the server itself (each mock request uses its own connection, and the DCP rate limit refuses rather than queues).

When the MCP client cancels a call (notifications/cancelled), a change that has not been sent yet is never sent: the server captures the request's cancel scope when the call starts and checks it right before each send, because the SDK only sets a flag and anyio may let the call run one more step first.

When the MCP client disconnects (stdin closes), pending requests are stopped: one still connecting or waiting to retry is never sent (not_sent), one already sent is not repeated, no new request starts, and the server exits with status 0.

Configuration

Set these as environment variables, for example in your MCP client's env block, or in a file passed with --env-file PATH. Values already in the environment win over the file. Settings are read when the server starts, and an unusable value (for example PROFINET_WRITES_ENABLED=maybe) stops it with a message on stderr. .env.example lists them all.

Without --env-file, the server also reads profinet-python/.env of a source checkout, found relative to the package source. It never reads a .env from the working directory or its parents (when an MCP client starts the server, that is the client's project, which may not be trusted; settings such as the mock address or the device map decide where a write goes), and an installed package reads no implicit .env at all. That file is applied defensively:

• safety switches (PROFINET_*_ENABLED) in it are ignored - they come only from the real environment or --env-file;
• it may set only PROFINET_* settings and DEVICE_MAP_FILE; anything else (PATH, LD_PRELOAD, PYTHONPATH, ...) is ignored;
• keys are compared case-insensitively (as Windows does), with export and quotes handled;
• each ignored key is named in a warning on stderr.

Booleans accept true/false, 1/0, yes/no, y/n, on/off and t/f.

DEVICE_MAP_FILE maps aliases to a device and slot, used by list_devices, read_device_by_alias and write_device_by_alias:

{
  "line1_inputs": {
    "device_name": "pn-device-01",
    "ip_address": "192.168.1.100",
    "description": "Line 1 digital inputs",
    "slot": 1,
    "subslot": 1,
    "data_length": 8
  }
}

slot is required (an alias without one is reported as an error rather than guessed); subslot defaults to 1 and data_length to 8. The file is re-read when it changes; if it cannot be parsed, list_devices and ping report the error.

Structure

profinet-python/
├── pyproject.toml
├── uv.lock
├── .env.example        # every setting; safety switches only via the real env or --env-file
├── .python-version
├── src/profinet_mcp
│   ├── __init__.py
│   ├── cli.py          # argument parsing, .env loading, startup
│   ├── config.py       # ProfinetConfig.from_env()
│   ├── server.py       # FastMCP wiring; bad arguments -> envelopes
│   ├── tools.py        # the 14 MCP tools
│   ├── validation.py   # MAC, station name, IP suite, slot checks
│   ├── pn_client.py    # safety switches, timing, routing to the backend
│   ├── backends.py     # none / mock (JSON over TCP) / network (DCP)
│   ├── dcp.py          # DCP Identify codec and Scapy layer-2 transport
│   └── gsd_parser.py   # GSDML parsing and cache
└── tests/              # pytest: unit tests and mock-backed integration tests

Tests

cd profinet-python
uv sync --locked
uv run --no-sync ruff check . && uv run --no-sync ruff format --check .
uv run --no-sync pytest

The integration tests start ../profinet-mock-server on an OS-assigned port and drive the server over stdio with the MCP client SDK. No test opens a raw socket: DCP is tested against fake layer-2 transports. The safety tests are mutation-checked: each one fails when the protection it covers is removed.

Dependency floors in pyproject.toml are the lowest versions the suite passes on; CI's lowest-direct job checks that with --resolution lowest-direct.