wago-plc-mcp-server

![wago-plc-mcp-server - bridge WAGO PLCs to AI agents](docs/media/hero-banner.svg)

<!-- mcp-name: io.github.WagoAlex/wago-plc-mcp-server -->

[![Docker Hub](https://img.shields.io/docker/pulls/wagoalex/wago-plc-mcp-server?color=6EC800)](https://hub.docker.com/r/wagoalex/wago-plc-mcp-server)
[![PyPI](https://img.shields.io/pypi/v/wago-plc-mcp-server?color=6EC800)](https://pypi.org/project/wago-plc-mcp-server/)
[![License: MPL-2.0](https://img.shields.io/badge/License-MPL%202.0-6EC800.svg)](LICENSE)
[![MCP Tools](https://img.shields.io/badge/MCP_tools-29-1F2837.svg)](#tool-reference)
[![Fleet tested](https://img.shields.io/badge/fleet_tested-16_PLCs-1F2837.svg)](#supported-hardware)

# wago-plc-mcp-server

> Talk to your WAGO PLC fleet the way you'd talk to a colleague. Ask an AI assistant to read, configure, and monitor your controllers in plain English - no scripts, no parameter IDs to memorize.

---

## Choose your path

| I am a... | I want to... | Start here |
|-----------|-------------|------------|
| **Claude Desktop / Claude Code user** | Connect my AI assistant to WAGO PLCs and start asking questions | **Part 1** → [Quick Start](#quick-start) → [What can I ask it?](#what-can-i-ask-it), or the one-file [Claude Desktop extension](#claude-desktop-extension-mcpb) |
| **Automation / OT engineer** | Understand what this does to my PLCs and whether it's safe | **Part 2** → [What this does and doesn't do](#what-this-does-and-doesnt-do) |
| **Software / DevOps engineer** | Deploy this in production with GitOps, TLS, and audit logging | **Part 3** → [Production deployment](#production-deployment) → [GitOps write-gate](#gitops-write-gate) |

Each part is self-contained top to bottom - a Claude Desktop user never needs
to read the GitOps internals, and a DevOps engineer never needs the chat
examples. [Reference](#frequently-asked-questions) at the end covers
cross-cutting material (FAQ, raw curl access, CRA compliance) that applies
regardless of persona.

---

## Architecture

```mermaid
%%{init: {'theme':'base', 'themeVariables': {
  'primaryColor':'#1F2837',
  'primaryTextColor':'#ffffff',
  'primaryBorderColor':'#6EC800',
  'lineColor':'#6EC800',
  'secondaryColor':'#EFF0F1',
  'secondaryTextColor':'#1F2837',
  'secondaryBorderColor':'#A5A8AF',
  'tertiaryColor':'#FFFFFF',
  'tertiaryTextColor':'#1F2837',
  'tertiaryBorderColor':'#DEDFE1',
  'fontFamily':'Segoe UI, Helvetica, Arial, sans-serif',
  'clusterBkg':'#EFF0F1',
  'clusterBorder':'#A5A8AF',
  'edgeLabelBackground':'#1F2837'
}}}%%
flowchart TB
    subgraph Clients["AI clients (any MCP client works)"]
        direction LR
        CD("Claude Desktop<br/>(direct HTTP)")
        CC("Claude Code<br/>(direct HTTP)")
        OC("OpenClaw<br/>(direct HTTP)")
    end
    %% Legacy/offline path: wago_proxy.py bridges stdio to HTTP for Claude
    %% Desktop clients too old to speak remote MCP directly - see Windows .exe

    CD & CC & OC -- "Bearer token" --> MCP

    subgraph Server["wago-plc-mcp-server - Docker, port 6042"]
        direction LR
        MCP("29 MCP tools<br/>find_parameters · get_parameter<br/>set_parameters · invoke_method<br/>create/read_watchlist · get_plc_audit_log · …")
        Guard("Bearer auth · rate limiting<br/>hash-chained audit log")
        MCP --- Guard
    end

    MCP --> FAN("WDA Bearer token + TLS<br/>parallel, semaphore-bounded<br/>fans out to every registered PLC")

    FAN --> P1 & P2 & P3 & P4 & P5 & P6 & Pn

    subgraph Fleet["WAGO PLC fleet"]
        direction LR
        P1("CC100")
        P2("PFC100 Gen 2")
        P3("PFC200 Gen 2")
        P4("PFC300")
        P5("Edge Controller")
        P6("WP400")
        Pn("TP600")
    end
    %% PFC400 (750-8400) omitted from this diagram - not yet in hand, see Supported hardware

    subgraph FW["fwupdate - separate tool, human-run only (v2.3.0)"]
        direction LR
        Op("Operator<br/>(maintenance window)") --> Az("Git-gated approval<br/>(policy committed + reviewed)")
        Az --> Flash("Firmware flash<br/>over WDA REST")
    end

    Flash --> P1 & P2 & P3 & P4 & P5 & P6 & Pn
    Flash -. shares the hash-chained audit log .-> Guard
```

Demoed end to end with **16 PLCs** of mixed device class on a single rack.
The parallel fan-out model has no architectural ceiling below **100+**.

Firmware updates are deliberately **not** an MCP tool - the server refuses
every firmware method so an agent can never flash a controller. `fwupdate/`
is a separate container a person runs by hand, and it refuses to start
without an approval already committed and reviewed in a git-tracked policy
file. See [`fwupdate/README.md`](fwupdate/README.md) for the full
authorization model.

---

# Part 1 - For Claude Desktop / Claude Code users

Everything to get connected and start asking questions in plain English.

## Demo

These are short screen recordings of the server driving real WAGO
controllers from Claude Desktop, start to finish - no edited-out steps.

### Overview - connecting Claude Desktop and a first interaction

![Overview demo](docs/media/demo-overview.gif)

<details>
<summary><strong>Use case 1 - fleet-wide health report across all 16 PLCs</strong></summary>

Asks the agent to reconcile a "health report" across the fleet - listing all
PLCs, bulk-fetching firmware versions, and probing device types to figure
out what's actually running where before trusting any conclusions.

![Use case 1 demo](docs/media/demo-use-case-1.gif)

</details>

<details>
<summary><strong>Use case 2 - Edge Controller: building a CPU/LED health watchlist</strong></summary>

Asks the agent to set up a watchlist monitoring CPU/service health and LED
diagnostic state on the Edge Controllers, then read it back - including the
agent pushing back to clarify ambiguous requirements before touching
anything, and discovering the actual parameter IDs via `find_parameters`
rather than guessing.

![Use case 2 Edge Controller demo](docs/media/demo-use-case-2-edge-controller.gif)

</details>

<details>
<summary><strong>Use case 2 - PFC300: building a CPU/LED health watchlist</strong></summary>

The same health-watchlist workflow as above, run against a PFC300 instead -
shows the same parameter-discovery process landing on different actual
parameter names for an equivalent capability.

![Use case 2 PFC300 demo](docs/media/demo-use-case-2-pfc300.gif)

</details>

<details>
<summary><strong>Use case 3 - detecting and fixing NTP drift fleet-wide</strong></summary>

Asks the agent to sync NTP time on any PLC that's drifted. The agent checks
NTP status across the entire fleet first, identifies which PLCs are
actually affected (stuck clocks, wrong timezone offsets), and only then
invokes the time-sync method on the specific units that need it.

![Use case 3 demo](docs/media/demo-use-case-3.gif)

</details>

<details>
<summary><strong>Use case 4 - which PLCs are reachable and what firmware are they running?</strong></summary>

Asks the agent to sweep the entire fleet, check reachability, and report
firmware versions - all in one shot. The agent calls `list_plcs`, then
`describe_plc` in parallel across every registered controller, and returns
a clean table of what's alive, what model it is, and which firmware build it
carries.

![Use case 4 demo](docs/media/demo-use-case-4.gif)

</details>

<details>
<summary><strong>Use case 5 - which devices still have the default NTP server configured?</strong></summary>

Asks the agent to audit NTP configuration across the fleet and flag any
controller still pointing at the factory-default time server. The kind of
compliance sweep that would otherwise require manual access to each device.

![Use case 5 demo](docs/media/demo-use-case-5.gif)

</details>

---

## Quick Start

### 1. Clone and configure

```bash
git clone https://github.com/WagoAlex/wago-plc-mcp-server.git
cd wago-plc-mcp-server
cp _env .env
```

Edit `.env`:

```env
WAGO_PLC_HOSTS=192.168.1.10,192.168.1.11,192.168.1.12
DEFAULT_PLC_USERNAME=admin
PORT=6042
WAGO_TIMEOUT_SECONDS=45
```

`WAGO_TIMEOUT_SECONDS` applies to every PLC in the fleet - set it to the
slowest device class you're onboarding, not the average. CC100 needs 45+;
most classes are fine at 15. IEC 62443-4-2-hardened units (see below) expose
roughly 3x the parameters of their base class and have not been timing-tuned
yet - if one fails registration with a timeout at 45s, that's a real open
question for this project, not a typo in this guide.

> [!TIP]
> For large fleets, use `WAGO_PLC_HOSTS_FILE=/app/data/fleet.txt` - one IP
> per line, `#` comments supported. Both can be set together; IPs are merged.

### 2. Set PLC passwords

Every device class onboards the same way: register its IP in step 1, then
give it credentials here. Two patterns, combinable:

**Shared password** (fleets where every PLC uses the same login):
```bash
mkdir -p secrets
echo "your-plc-password" > secrets/plc_default_password.txt
chmod 600 secrets/plc_default_password.txt
```

**Per-PLC password** (any unit with its own login - common for hardened or
customer-managed devices): add a secret named for its IP, then uncomment the
matching lines in `docker-compose.yml` (`secrets:` block and the service's
`secrets:` list):
```bash
echo "that-unit-password" > secrets/plc_password_192_168_2_85.txt
chmod 600 secrets/plc_password_192_168_2_85.txt
```
Per-PLC secrets take priority over the shared default for a matching IP, so a
mixed fleet just needs one of these per unit that doesn't share the default
login - everything else falls back to `plc_default_password.txt`.

> [!IMPORTANT]
> **Onboarding IEC 62443-4-2-hardened units (CC100-IEC62443, and the planned
> PFC400 family).** These register and behave like any other PLC - same WDA
> API, same tools - but almost always ship with their own credentials, so
> they need the per-PLC pattern above, not the shared default.
> - **CC100-IEC62443** (order no. `751-9412`) is a hardened CC100 variant:
>   registers under `device_class: "CC100"` (same order-number pr