Skip to main content
Glama

🏭 plc-mcp

Posez vos questions à un automate industriel en langage naturel.

Un serveur MCP en Python qui se connecte à un automate en OPC UA et expose ses données à n'importe quel assistant IA : Claude Desktop, Claude Code ou votre propre agent LangGraph. Livré avec un simulateur de ligne de production, pour fonctionner sans vraie machine.

Python MCP OPC UA Docker CI Type

« Quelle est la température du four 2 ? » « Pourquoi la ligne s'est-elle arrêtée cette nuit ? » « Génère la doc des variables de cet automate. »


✨ Fonctionnalités

  • Lecture en direct des capteurs, compteurs et alarmes, avec l'unité, l'horodatage et la qualité OPC UA.

  • Diagnostic d'arrêt : journal_evenements reconstruit chaque arrêt avec sa cause, sa durée, l'alarme déclenchante et les variables à examiner. L'assistant creuse ensuite avec historique pour remonter du symptôme (l'alarme) à la cause racine (la commande de chauffe saturée).

  • Historique résumé pour un LLM : min, max et moyenne, plus une courbe sous-échantillonnée qui garde les pics. Pour un booléen ou un code, on obtient la liste des changements d'état. On ne renvoie jamais 10 000 points bruts.

  • Documentation automatique : l'automate est parcouru (browse OPC UA) pour produire une fiche Markdown des variables (type, unité, plage, droits, valeur, description). Les variables mal documentées dans l'automate sont signalées.

  • Écriture sous garde-fous : lecture seule par défaut, liste blanche, bornes, variation maximale, confirmation en deux temps et journal d'audit (détails plus bas).

  • Simulateur réaliste : deux fours, un convoyeur, de l'air comprimé, des alarmes et 36 h d'historique déjà rejouées, avec un incident la nuit dernière à expliquer.

  • Deux transports : stdio (Claude Desktop, Claude Code) et Streamable HTTP (Docker, agents distants).

Ce que voit l'assistant

Type

Nom

Rôle

🔧 tool

lister_variables(dossier?)

Catalogue découvert sur l'automate

🔧 tool

lire_variable(chemin) · lire_variables(chemins)

Valeurs actuelles

🔧 tool

lister_alarmes()

Alarmes actives et depuis quand

🔧 tool

historique(chemin, periode | debut, fin)

Historique résumé (30min, 8h, 2j, nuit, ou dates ISO)

🔧 tool

journal_evenements(periode)

Arrêts, causes, durées et chronologie des alarmes

🔧 tool

ecrire_variable(chemin, valeur)

Prépare une écriture et renvoie un jeton

🔧 tool

confirmer_ecriture(jeton) · annuler_ecriture(jeton)

Exécute ou abandonne l'écriture

🔧 tool

generer_documentation()

Fiche Markdown complète

📄 resource

plc://variables · plc://variables/{chemin}

Catalogue et fiche d'une variable

📄 resource

plc://documentation · plc://politique-ecriture

Doc générée, garde-fous en vigueur

💬 prompt

diagnostic_arret(periode)

Méthode guidée pour expliquer un arrêt

Related MCP server: Industrial-AIops

🧠 Comment ça marche

flowchart LR
    subgraph Clients["Assistants IA"]
        CD[Claude Desktop]
        CC[Claude Code]
        LG[Agent LangGraph]
    end
    subgraph MCP["plc-mcp (serveur MCP)"]
        T[Tools · Resources · Prompt]
        G{{Garde-fous<br/>écriture}}
        A[Analyse<br/>résumé · journal]
        D[Docgen]
        P[Client OPC UA<br/>browse · read · history]
    end
    subgraph PLC["Automate (ici : simulateur)"]
        S[(Espace d'adresses OPC UA<br/>21 variables + historique)]
        M[Modèle physique<br/>fours · convoyeur · alarmes]
    end
    CD & CC -- stdio --> T
    LG -- Streamable HTTP --> T
    T --> A --> P
    T --> D --> P
    T -- écriture --> G --> P
    P -- opc.tcp --> S
    M <--> S

Pourquoi OPC UA plutôt que Modbus ? En Modbus, un automate n'expose que des numéros de registres : la signification de chaque registre vit dans un tableur à part. En OPC UA, l'automate décrit lui-même ses variables (nom, description, unité, plage, droits, historisation). Le serveur MCP découvre donc tout par browse, sans rien coder en dur, et la documentation automatique reflète la machine réelle. Un connecteur Modbus reste possible, avec une table de correspondance en YAML (voir les pistes d'amélioration).

Le serveur MCP ne connaît pas le simulateur. Il n'importe rien de plc_mcp.simulator : il parcourt l'espace d'adresses comme il le ferait sur un vrai automate. Les seules conventions sont réglables par variables d'environnement : le dossier des alarmes, la variable de marche et le code d'arrêt. Les libellés des codes d'arrêt sont même lus dans la description OPC UA de la variable.

Le scénario rejoué par le simulateur

Au démarrage, le simulateur rejoue les 36 dernières heures pas à pas. L'historique OPC UA contient donc déjà :

Quand

Événement

Veille, 12:00 → 12:30

Pause déjeuner (arrêt opérateur)

Veille, ~16:25

Bourrage du convoyeur : surintensité moteur, arrêt de 9 min

Nuit, 03:05

Le relais de chauffe du four 2 colle. Le four atteint 225 °C, l'alarme se déclenche, la sécurité coupe la chauffe et la ligne s'arrête (03:07).

Nuit, 03:45

La maintenance remplace le relais. Le four remonte en température.

Nuit, 04:17

Redémarrage par l'opérateur

Si on demande « pourquoi la ligne s'est arrêtée cette nuit ? », l'assistant appelle journal_evenements puis historique sur Four2.Temperature et Four2.PuissanceChauffe. Il voit la puissance bloquée à 100 % avant l'alarme et en déduit la cause racine.

🛡️ Garde-fous d'écriture

Laisser un LLM écrire dans un automate est risqué. Une écriture doit donc franchir cinq contrôles (guards.py) :

#

Contrôle

Par défaut

1

Interrupteur général PLC_MCP_WRITE_ENABLED

désactivé : lecture seule stricte

2

Liste blanche config/ecriture.yaml

3 consignes, pas la commande de marche

3

Droit d'écriture déclaré par l'automate (AccessLevel OPC UA)

les mesures sont en lecture seule

4

Type, bornes min/max et variation maximale max_step

230 °C au plus, ±10 °C par écriture

5

Confirmation : ecrire_variable ne fait que préparer la demande. confirmer_ecriture exécute un jeton à usage unique, valable 2 min.

—

Après l'écriture, la valeur est relue dans l'automate. Chaque demande (refusée, confirmée, expirée, échouée) est tracée dans logs/audit-ecritures.jsonl.

Ligne.CommandeMarche illustre la défense en profondeur : l'automate accepte qu'on l'écrive, mais elle est volontairement absente de la liste blanche. Démarrer une ligne reste une action humaine.

Limite assumée. La confirmation en deux temps ne garantit pas, à elle seule, qu'un humain a validé : un modèle mal aligné pourrait enchaîner les deux appels. Elle s'appuie donc sur les annotations MCP (destructiveHint sur confirmer_ecriture), qui poussent les clients comme Claude Desktop à demander l'accord de l'utilisateur avant chaque appel. Le vrai verrou reste l'ensemble liste blanche + bornes + droits automate. L'élicitation MCP figure dans les pistes d'amélioration.

🚀 Démarrage rapide

Prérequis : uv, ou Docker.

Option A : Docker Compose (simulateur + serveur MCP en HTTP)

docker compose up --build
claude mcp add --transport http plc http://localhost:8000/mcp   # Claude Code

Si le port 8000 est déjà occupé : PLC_MCP_PORT=8010 docker compose up --build. Pour autoriser les écritures de la liste blanche : PLC_MCP_WRITE_ENABLED=true docker compose up.

Option B : en local avec Claude Desktop (stdio)

uv sync
uv run plc-sim                       # terminal 1 : l'automate simulé sur opc.tcp://localhost:4840

Puis, dans claude_desktop_config.json (menu Réglages > Développeur > Modifier la config) :

{
  "mcpServers": {
    "automate": {
      "command": "uv",
      "args": ["--directory", "/chemin/absolu/vers/plc-mcp", "run", "plc-mcp"],
      "env": {
        "PLC_MCP_ENDPOINT": "opc.tcp://localhost:4840/plc-mcp/",
        "PLC_MCP_WRITE_ENABLED": "false"
      }
    }
  }
}

Le simulateur peut aussi tourner seul dans Docker : docker compose up plc-sim.

Générer la fiche des variables

uv run plc-doc -o docs/variables.md

Tests

uv run pytest        # 58 tests, dont un bout en bout : vrai simulateur OPC UA <-> client MCP
uv run ruff check .

La CI GitHub Actions lance le lint, les tests, puis démarre la stack Docker Compose et appelle le serveur MCP en HTTP.

Configuration

Variable

Défaut

Rôle

PLC_MCP_ENDPOINT

opc.tcp://localhost:4840/plc-mcp/

Adresse de l'automate

PLC_MCP_WRITE_ENABLED

false

Interrupteur général des écritures

PLC_MCP_WRITE_POLICY

config/ecriture.yaml

Liste blanche

PLC_MCP_CONFIRMATION_TTL_S

120

Validité d'un jeton d'écriture

PLC_MCP_TIMEZONE

Europe/Paris

Fuseau de l'usine (affichage, « cette nuit »)

PLC_MCP_MAX_HISTORY_POINTS

120

Budget de points par historique

PLC_MCP_NAMESPACE_URI · PLC_MCP_ROOT

urn:plc-mcp:ligne-production · LigneProduction

Où explorer

PLC_MCP_ALARM_FOLDER · PLC_MCP_RUN_VARIABLE · PLC_MCP_STOP_CODE_VARIABLE

Alarmes · Ligne.EnMarche · Ligne.CodeArret

Signaux du journal d'arrêts

Avec Claude Code (le plus simple)

Le dépôt contient un .mcp.json : lancé dans ce dossier, Claude Code propose d'activer le serveur automate.

uv run plc-sim          # terminal 1
claude                  # terminal 2, dans le dossier plc-mcp : accepter le serveur « automate »

Regénérer le GIF de démo

Le GIF n'est pas une capture d'écran : c'est le rendu de vraies sessions Claude Code, ce qui le rend reproductible et léger (0,1 Mo).

uv run plc-sim &                                   # l'automate simulé
for q in "Quelle est la température du four 2 ?" "Pourquoi la ligne s'est arrêtée cette nuit ?"; do
  claude -p "$q" --strict-mcp-config --mcp-config .mcp.json --allowedTools mcp__automate \
    --output-format stream-json --verbose > "session-$((++i)).jsonl"
done
python scripts/extract_transcript.py session-*.jsonl -o docs/demo/transcript.json \
  --questions "Quelle est la température du four 2 ?" "Pourquoi la ligne s'est arrêtée cette nuit ?"
uv run scripts/render_demo.py                      # -> docs/demo.gif

Pour la démo, les sessions ont été lancées avec la consigne système « réponds de façon concise, 6 lignes au maximum », afin que les réponses tiennent à l'écran.

Pour une vraie capture d'écran, sous Ubuntu : Ctrl + Maj + Alt + R pour enregistrer, puis scripts/make-gif.sh ~/Vidéos/Screencasts/<fichier>.webm pour convertir la vidéo en GIF.

📁 Structure du projet

plc-mcp/
├── src/plc_mcp/
│   ├── server.py            # serveur MCP : tools, resources, prompt, transports
│   ├── plc.py               # client OPC UA : browse, lecture, historique, écriture, reconnexion
│   ├── guards.py            # garde-fous d'écriture + audit
│   ├── analysis.py          # périodes, résumés d'historique, journal des arrêts (fonctions pures)
│   ├── docgen.py            # fiche Markdown des variables (+ CLI plc-doc)
│   ├── config.py            # réglages PLC_MCP_*
│   └── simulator/
│       ├── model.py         # modèle physique de la ligne + scénario d'incidents
│       └── server.py        # serveur OPC UA : métadonnées, historique, rejeu (CLI plc-sim)
├── config/ecriture.yaml     # liste blanche d'écriture
├── scripts/
│   ├── extract_transcript.py  # session Claude Code -> transcript propre
│   ├── render_demo.py         # transcript -> docs/demo.gif
│   └── make-gif.sh            # capture d'écran -> GIF
├── .mcp.json                # déclaration du serveur pour Claude Code
├── docs/
│   ├── variables.md         # fiche générée automatiquement
│   ├── demo.gif             # démo
│   └── demo/transcript.json # sessions réelles utilisées pour la démo
├── tests/                   # modèle, garde-fous, analyse, docgen, bout en bout
├── Dockerfile               # une image pour les deux services
├── docker-compose.yml
└── .github/workflows/ci.yml

🗺️ Pistes d'amélioration

  • Confirmation par élicitation MCP : le serveur demande l'accord directement à l'utilisateur, sans passer par le modèle, quand le client le permet.

  • Connecteur Modbus TCP (pymodbus), avec une table de correspondance des registres en YAML, derrière la même interface que le client OPC UA.

  • Sécurité OPC UA : certificats, Basic256Sha256 et authentification utilisateur. Authentification OAuth sur le transport HTTP.

  • Alarmes OPC UA natives (Alarms & Conditions) à la place des booléens, et historique d'événements.

  • Historien persistant (SQLite ou TimescaleDB) pour garder l'historique au-delà d'un redémarrage.

  • Évaluation : un jeu de questions annotées (« pourquoi l'arrêt ? ») pour mesurer la justesse des diagnostics de différents modèles, dont des modèles locaux.

  • Déploiement Kubernetes (Helm) avec le simulateur en sidecar.

👤 Auteur

Cyril D'Houdetot · GitHub

Projet personnel, sous licence MIT.

Available Tools

10 tools
annuler_ecritureC
Read-only

Annule une demande d'écriture en attente.

Inputs: jeton (required). Returns: object

confirmer_ecritureA
Destructive

ÉCRIT réellement dans l'automate une demande préparée par ecrire_variable.

    À n'appeler qu'après l'accord explicite de l'utilisateur. Le jeton est à usage unique.
    

Inputs: jeton (required). Returns: object

ecrire_variableA
Read-only

PRÉPARE l'écriture d'une variable, sans rien écrire. Renvoie un jeton de confirmation.

    Contrôles : serveur en mode écriture, variable en liste blanche, inscriptible par l'automate,
    type et bornes respectés, variation limitée. Montre ensuite le récapitulatif à l'utilisateur
    et attends son accord explicite avant d'appeler confirmer_ecriture.
    

Inputs: chemin (required), valeur (required). Returns: object

generer_documentationA
Read-onlyIdempotent

Parcourt l'automate et génère la fiche Markdown de toutes ses variables (type, unité, plage, droits, valeur actuelle, description), ainsi que la politique d'écriture.

Inputs: no named parameters. Returns: result

historiqueA
Read-onlyIdempotent

Historique d'une variable sur une période, résumé pour rester lisible.

    Variables numériques : min, max (avec horodatage), moyenne et une courbe sous-échantillonnée qui
    conserve les pics. Booléens et codes : liste des changements d'état.

    Args:
        chemin: variable, ex. « Four2.Temperature ».
        periode: durée glissante jusqu'à maintenant (« 30min », « 8h », « 2j ») ou « nuit » (22 h → 6 h).
        debut: date ISO 8601 de début (heure locale), prioritaire sur periode. Ex. « 2026-11-19T02:30 ».
        fin: date ISO 8601 de fin (défaut : maintenant).
    

Inputs: chemin (required), fin, debut, periode. Returns: object

journal_evenementsA
Read-onlyIdempotent

Chronologie des alarmes et des arrêts de la ligne, avec la cause et la durée de chaque arrêt.

    C'est l'outil à utiliser pour répondre à « pourquoi la ligne s'est-elle arrêtée ? ».

    Args:
        periode: « 30min », « 8h », « 2j » ou « nuit » (22 h → 6 h, la plus récente).
        debut: date ISO 8601 de début (heure locale), prioritaire sur periode.
        fin: date ISO 8601 de fin.
    

Inputs: fin, debut, periode. Returns: object

lire_variableA
Read-onlyIdempotent

Lit la valeur actuelle d'une variable (ex. « Four2.Temperature »), avec unité, horodatage et qualité.

Inputs: chemin (required). Returns: object

lire_variablesB
Read-onlyIdempotent

Lit plusieurs variables en une seule requête à l'automate.

Inputs: chemins (required). Returns: object

lister_alarmesA
Read-onlyIdempotent

Liste les alarmes de l'automate, actives en premier, avec l'heure de leur dernier changement.

Inputs: no named parameters. Returns: object

lister_variablesA
Read-onlyIdempotent

Liste les variables de l'automate (chemin, type, unité, plage, description, droits).

    Args:
        dossier: filtre optionnel sur un groupe (ex. « Four2 », « Alarmes »).
    

Inputs: dossier. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 10 tools

    Disambiguation4/5

    The read surface is cleanly split: lister_variables lists metadata, lire_variable/lire_variables read values, and historique pulls time series; the singular/plural pair is spelled out well in the descriptions. The only real overlap is between lister_alarmes and journal_evenements, which both surface alarm chronologies (the latter adds stops and causes), so an agent could occasionally pick the wrong one. The three-step write flow (ecrire/confirmer/annuler) is explicitly delineated.

    Naming Consistency4/5

    Eight of ten tools use a verb_noun French pattern (lister_*, lire_*, ecrire_*, confirmer_*, annuler_*, generer_documentation) with consistent lowercase snake_case. The exceptions are 'historique' and 'journal_evenements', which are noun-only names and break the verb-first convention. The style is otherwise uniform and readable.

    Tool Count5/5

    Ten tools is well within a comfortable scope for a PLC monitoring/control server. Each tool earns its place: the split write-offer/confirm/cancel trio is justified by the safety requirement of operator confirmation, and no tool is redundant filler.

    Completeness4/5

    The surface covers listing, single and batch reads, history, alarm/event timelines, a guarded write lifecycle, and documentation generation — a solid lifecycle for the domain. Gaps remain: no alarm acknowledgement/reset, no batch write preparation, and no live subscription or polling for value changes. Agents can work around these but they are real omissions.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI agents to OPC UA-enabled industrial systems for real-time monitoring and control of operational data. It enables users to read, write, and browse industrial device nodes through natural language interactions.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Provides AI agents with safe, governed read access to industrial control systems (OPC-UA, Modbus, S7, Mitsubishi, MTConnect, MQTT/Sparkplug) plus cross-protocol diagnostics for troubleshooting data breaks, alarm floods, and unhealthy tags.
      157
      13
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables LLMs to read, write, browse, search, and subscribe to live data on OPC-UA industrial automation servers, with caching, discovery index, and support for stdio or HTTP transports.
      5
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that connects a local LLM to an industrial PLC via Modbus TCP, enabling process reading, alarm correlation, and safe diagnosis with restricted write access through an allowlist. Includes a simulated PLC with real physics for local testing.
      -