Proxus Industrial MCP Server

[图片] Proxus Industrial MCP Server

Gives AI assistants such as Claude Desktop, Cursor and VS Code read-only access to industrial devices. Supports Modbus TCP and OPC UA (Basic256Sha256, Aes128_Sha256_RsaOaep or Aes256_Sha256_RsaPss with Sign or SignAndEncrypt, or unsecured; anonymous or user-name login).

[An AI assistant reads a PLC, decodes a meter value and diagnoses a device that does not answer]

Condensed from a real session against simulated devices (docs/demo.json). More at proxus.io/tools/industrial-mcp-server.

Tools

Nothing can write to a device.

Register maps

With a register map the assistant reads voltage_l1_n instead of guessing that hr:0-1 is a word-swapped float. A map lists every register of a device model: address, data type, byte order, scale (fixed, or a SunSpec scale-factor register), unit and the meaning of enumerated values, with the vendor document it comes from. The binaries include the open Modbus Register Maps collection (energy meters, power analysers, drives, inverters); each release also attaches it as register-maps.json.gz.

Give a Modbus device its map in the configuration, by id or as the path of a map's JSON file:

"meter-1": { "protocol": "modbus-tcp", "host": "192.168.10.40", "map": "schneider-electric/pm5500-pm5600-pm5700" }

maps_dir adds maps (or replaces built-in ones with the same id) from a folder of JSON files, as python3 tools/maps.py build in the collection writes them. A map that does not exist stops the server at start-up with the reason. Maps tell the assistant how to read a register, never to write one: read_named only reads.

Verify a map on your device

Most maps are transcribed from vendor documents. Ask your assistant to verify the device's map: verify_device_map reads every register once (read-only), checks that the values are plausible (floats, frequency, voltage, power factor, energy counters, model) and asks you to compare two values with the device's display. The result is a report and a link that opens a prefilled issue in the map collection; you submit it under your own GitHub account, and a bot adds you to the map's verified list. Nothing is sent without you, and the report holds check results only, no addresses, host names or serial numbers.

OPC UA security

Set security_mode (sign_and_encrypt, sign or none) and security_policy (Basic256Sha256, Aes128_Sha256_RsaOaep or Aes256_Sha256_RsaPss) per device. Certificates live in pki_dir (default pki/ next to the configuration file), in the layout most OPC UA tools use:

Trust is never automatic, in either direction:

1. On the first connection the server's certificate lands in rejected/ and the tool answers with its SHA-256 thumbprint. Confirm the thumbprint with the server's administrator, then move the file to trusted/.
2. If the server answers BadCertificateUntrusted or BadSecurityChecksFailed, it has not trusted this client yet. proxus-mcp certificate --config <file> prints this server's certificate file and thumbprint to trust on the server.

Passwords never go in the configuration file: password_env names the environment variable that holds them. Errors carry the OPC UA StatusCode name, the specification's description and a suggested next step.

Install

Download the archive for your platform from the releases page, unpack it, and point your MCP client at the proxus-mcp binary (see Claude Desktop below). Each archive has a .sha256 file next to it. The binaries are not code-signed yet: on macOS run xattr -d com.apple.quarantine proxus-mcp once after unpacking, and on Windows choose "More info, Run anyway" the first time.

proxus-mcp --version prints the version.

Docker

docker run -i --rm -v "$PWD:/config" ghcr.io/proxus-io/proxus-mcp:<version>

The image reads /config/proxus-mcp.json and speaks MCP over stdin/stdout, so an MCP client starts it with docker as the command and run -i --rm -v <folder>:/config ghcr.io/proxus-io/proxus-mcp:<version> as the arguments. Devices on the host are reachable as host.docker.internal; on Linux add --network host to reach the plant network directly. Images are published for linux/amd64 and linux/arm64.

Build

Needs the .NET 10 SDK. The protocol drivers come from the Proxus.Drivers NuGet packages (Apache-2.0).

dotnet publish src/Proxus.Mcp.Server -c Release -r osx-arm64 -o artifacts/osx-arm64

The result is one native file, artifacts/osx-arm64/proxus-mcp (about 10 MB).

Claude Desktop

Add to claude_desktop_config.json:

{  "mcpServers": {    "proxus": {      "command": "/absolute/path/to/proxus-mcp",      "args": ["--config", "/absolute/path/to/proxus-mcp.json"]    }  }}

Copy proxus-mcp.example.json as a starting configuration.

Tests

• dotnet test tests/Proxus.Mcp.Tests: unit tests, no devices needed.
• tests/smoke/run_all.sh: the published binary against Modbus and OPC UA simulators (see tests/smoke/README.md).
• CI (.github/workflows/ci.yml) runs both and publishes Native AOT binaries for linux-x64, linux-arm64, win-x64 and osx-arm64.

Licence

Apache-2.0, see LICENSE.