industrial-mcp

An MCP server that gives Claude (or any MCP-compatible AI host) read access to industrial sensor data and safety-gated control over motors and actuators.

The hard part of Physical AI isn't getting a language model to talk about a factory — it's getting it to act on one without anyone losing sleep. That requires three boring things working together:

1. Tool schemas the model can understand and call correctly.

2. Safety preconditions that block dangerous actions even when the model is confident.

3. An audit trail that survives the next post-mortem.

This repo is a working implementation of all three, in under 500 lines of Python, using FastMCP. Default mode is read-only and ships with a deterministic mock adapter modeling a 7-silo grain storage facility, so it runs in CI with no infrastructure.

The read path is verified end to end against real hardware: an ESP32-S3 with DS18B20 probes on a OneWire mux, answering a model's questions about grain temperature over the LAN. Warming one probe by hand moved max_temp_c from 28.0 to 31.0 — and dropped the average, because the other probe was in cold water. That measurement is why these tools return min, max, and faulted_sensors instead of one reassuring number. Evidence, including what is not verified: docs/hardware-verification.md (español).

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│  MCP host  (Claude Desktop, Claude Code, Cursor, etc.)              │
│   user prompt ──► model decides which tool to call                  │
└──────────────────────────────┬──────────────────────────────────────┘
                               │  stdio  (JSON-RPC over MCP)
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│  industrial-mcp  (this repo)                                        │
│                                                                     │
│   server.py ── wires tools, env config, audit log                   │
│      │                                                              │
│      ├── tools.py ── 5 read tools + 1 write tool (dry-run default)  │
│      │                                                              │
│      ├── safety.py ── preconditions, advisory warnings              │
│      │                                                              │
│      ├── audit.py ── append-only JSONL of executed actions          │
│      │                                                              │
│      └── adapters/                                                  │
│            ├── base.py    ← PlantAdapter protocol (the contract)    │
│            ├── mock.py    ← default, deterministic demo data        │
│            └── esp32.py   ← HTTP to a live SiloScan module          │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
            ┌──────────────────┼──────────────────┐
            ▼                  ▼                  ▼
   [MQTT broker]      [internal REST API]   [historian / TSDB]

Related MCP server: MCP PLC Core

Quick start

Run the server, talk to it from Claude Desktop, see it work.

# 1. Run the server with the mock adapter (no infra required)
uvx industrial-mcp@latest

# 2. Add this to ~/Library/Application Support/Claude/claude_desktop_config.json
#    (macOS) — see examples/claude-desktop-config.json

Then in Claude Desktop:

¿Qué silos tienen alerta crítica hoy?

Claude calls list_plants → get_active_alerts → answers with the data. See examples/demo-transcript.md for a full session.

To enable live (non-dry-run) execution against the mock adapter:

INDUSTRIAL_MCP_ALLOW_WRITES=true uvx industrial-mcp@latest

This flag does not affect dry runs — those always work. It only unlocks the path where a tool call would actually mutate state.

Tools exposed over MCP

Tool schemas live in src/industrial_mcp/tools.py. Keep their docstrings short and exact — they become the model's tool descriptions.

Why three layers of safety, not one

trigger_motor_action will only execute when all of the following hold:

1. The LLM explicitly sets dry_run=False.

2. The call includes an operator_id and a reason.

3. The server itself was started with INDUSTRIAL_MCP_ALLOW_WRITES=true.

4. Every precondition in safety.evaluate_motor_action passes.

Step 3 is the one that matters most. The model can hallucinate dry_run=False; the operator field can be spoofed by a clever prompt; the safety check can have a bug. But if the server was started read-only, none of that touches a motor. The deploy posture is the last word, not the prompt.

Every executed call is appended to an append-only JSONL audit log:

{"ts": 1779600000.12, "actor": "op-42", "action": "motor.start",
 "target": "fan-7-1", "outcome": "applied",
 "details": {"reason": "silo-7 at 32.1°C, manual fan-on"}}

Dry runs are not logged. They're not interesting and they'd dilute the signal.

Adapters

The contract every adapter must satisfy lives in src/industrial_mcp/adapters/base.py as a PlantAdapter Protocol — list_plants, list_silos, get_silo_thermometry, list_motors, get_motor, get_plant_context, get_active_alerts, apply_motor_action. Motor records must carry plant_id; the tool layer resolves plant context from the motor rather than from a constant, so a motor without one is refused instead of evaluated against the wrong plant.

INDUSTRIAL_MCP_ADAPTER selects which one runs. It knows mock (deterministic, shipped, used by CI) and esp32 (HTTP to a live SiloScan thermometry module). An unrecognized name raises at startup — the server never falls back to the mock, because answering questions about a plant you are not connected to is worse than refusing to start.

INDUSTRIAL_MCP_ADAPTER=esp32 \
INDUSTRIAL_MCP_ESP32_HOST=banco-silo3.local \
INDUSTRIAL_MCP_ESP32_DEVICE_ID=banco-silo3 \
INDUSTRIAL_MCP_ESP32_CABLES=0,8 \
uv run industrial-mcp

INDUSTRIAL_MCP_ESP32_CABLES defaults to channel 0 alone — each channel costs a OneWire conversion, so the default is cheap rather than complete. Leaving it out silently drops every other probe.

Use a name, not an address. Firmware 0.5.0+ publishes <device_id>.local over mDNS. DHCP will move the address out from under any file you write it into — the bench module took three different leases in three reboots, and every stale config in this repo's history traces back to that.

INDUSTRIAL_MCP_ESP32_DEVICE_ID is optional and turns on self-healing: when the configured host stops answering, the adapter looks the module up by name, then by subnet sweep, and adopts the new address only if the device identifies itself as that id. Without it the adapter reports device_unreachable instead of guessing — a sweep cannot tell "my module moved" from "some other module answered", and silo 3's tools reading silo 7's sensors would produce numbers that look perfectly reasonable and come from the wrong bin.

The scan_devices tool exposes the same sweep to the model, read-only: it reports what answered and never edits configuration. Scanning is restricted to private address space and to ranges of /22 or smaller.

Two things the esp32 adapter does that are worth copying into your own adapter, both of them about not laundering a sensor fault into a plausible number:

• A reading counts only when the firmware classified it valid and the temperature is actually present. Averaging a missing reading as 0 °C is how a hot silo reads cool.

• An unreachable module returns {"error": "device_unreachable"}, never an exception and never a stale number wearing a fresh timestamp. The timestamp comes from the machine doing the read, because the module's clock is only right after an NTP sync.

To talk to a different plant, drop a sibling module implementing the Protocol and add its name to build_adapter in server.py.

Development

git clone https://github.com/brayangcastro/mcp-industrial-agent
cd mcp-industrial-agent
uv sync --extra dev
uv run pytest -v
uv run ruff check src tests

CI runs the same two commands on Python 3.11 and 3.12 — see .github/workflows/ci.yml.

FAQ

Why not just give the model raw API keys? Because then every prompt injection is one HTTP call away from a production motor. The MCP surface is narrow on purpose: the model sees six functions, not your AWS console.

Why a separate dry_run flag instead of a confirmation step? Confirmation steps add latency and break flow. The dry run returns the outcome the model would have caused — preconditions, warnings, state delta — as data the model can keep reasoning over. Live execution is then a one-line escalation, not a five-prompt dance.

Is the audit log enough for compliance? No. It's enough to reconstruct what happened. It is not enough on its own for IEC 62443, IATF 16949, or similar. Pair it with your plant's existing change-management system; this repo is a starting point, not a finished compliance story.

Is this only a mock? Where's MQTT / OPC UA? No longer only a mock — the esp32 adapter reads a live device over HTTP, and the read path is verified against it. MQTT and OPC UA are still absent, and they are usually plant-specific anyway: the broker URLs, topic structures, and ACLs you can publish publicly are usually zero. The PlantAdapter Protocol is the extension point.

So the safety gate is proven against real equipment? Against a real pin, yes. Firmware 0.4.0 exposes /api/relay, and the four-step escalation was run against it: dry run left the pin low, a call without operator_id was rejected with the pin low, a read-only server rejected it with the pin low, and only the fourth call drove it high. Be precise about the limit, though — that is a logic-level GPIO with an LED on it, not a three-phase fan with inrush current and interlocks. What was proven is that the gate stops a real actuator from moving; motor sequencing is a different problem.

How do you know the relay actually switched? Because the module is asked, not trusted. GET /api/relay reports the level read back off the pad next to the command it was given, and apply_motor_action decides success from the reading. A 200 response with the pin still low comes back as a fault. An actuator that only repeats the order it was given is not telemetry, it is an echo.

Status

Read and write paths both verified against hardware. Not 1.0 — the shapes are stable, but expect breaking changes in non-public APIs.

Author

Built and maintained by Brayan Castro — Ing. Mecatrónica (ITESM Sonora Norte), operating BC Ingeniería from Guasave, Sinaloa. Background: 4+ years building IoT systems for agroindustrial grain handling (firmware ESP32 + thermocouple MUX + cloud), backend services for property management and POS, and conversational AI agents on top of Claude / GPT-4o. Reach out: info@ingebc.com.

License

MIT — see LICENSE.