plc-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@plc-mcp Why did the production line stop last night?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🏭 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.
« 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_evenementsreconstruit chaque arrêt avec sa cause, sa durée, l'alarme déclenchante et les variables à examiner. L'assistant creuse ensuite avechistoriquepour 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 |
| Catalogue découvert sur l'automate |
🔧 tool |
| Valeurs actuelles |
🔧 tool |
| Alarmes actives et depuis quand |
🔧 tool |
| Historique résumé ( |
🔧 tool |
| Arrêts, causes, durées et chronologie des alarmes |
🔧 tool |
| Prépare une écriture et renvoie un jeton |
🔧 tool |
| Exécute ou abandonne l'écriture |
🔧 tool |
| Fiche Markdown complète |
📄 resource |
| Catalogue et fiche d'une variable |
📄 resource |
| Doc générée, garde-fous en vigueur |
💬 prompt |
| 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 <--> SPourquoi 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 | désactivé : lecture seule stricte |
2 | Liste blanche | 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 | 230 °C au plus, ±10 °C par écriture |
5 | Confirmation : | — |
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 (
destructiveHintsurconfirmer_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 CodeSi 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:4840Puis, 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.mdTests
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 |
|
| Adresse de l'automate |
|
| Interrupteur général des écritures |
|
| Liste blanche |
|
| Validité d'un jeton d'écriture |
|
| Fuseau de l'usine (affichage, « cette nuit ») |
|
| Budget de points par historique |
|
| Où explorer |
|
| 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.gifPour 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,
Basic256Sha256et 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 toolsannuler_ecritureCRead-only
Annule une demande d'écriture en attente.
Inputs: jeton (required). Returns: object
confirmer_ecritureADestructive
É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_variableARead-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_documentationARead-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
historiqueARead-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_evenementsARead-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_variableARead-onlyIdempotent
Lit la valeur actuelle d'une variable (ex. « Four2.Temperature »), avec unité, horodatage et qualité.
Inputs: chemin (required). Returns: object
lire_variablesBRead-onlyIdempotent
Lit plusieurs variables en une seule requête à l'automate.
Inputs: chemins (required). Returns: object
lister_alarmesARead-onlyIdempotent
Liste les alarmes de l'automate, actives en premier, avec l'heure de leur dernier changement.
Inputs: no named parameters. Returns: object
lister_variablesARead-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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Query Allen-Bradley and Siemens PLC projects, live tag values, and analyses in plain English.
Industrial glossary, protocol reference, technical search and OEE calculation. Read-only.
Manufacturing BI from your AI client: dashboards, OEE, spreadsheets, scheduling, text-to-CAD.
Company and industrial data for AI assistants: datasets, SQL, dashboards, alarms, with approvals.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects 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
- AlicenseBqualityBmaintenanceProvides 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.15713MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.5MIT
- FlicenseNot gradedqualityDmaintenanceAn 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.-