Predictive Maintenance MCP

Servidor MCP de Predictive Maintenance

Dale a tu asistente de IA diagnósticos de vibración basados en evidencia: detección de fallos de maquinaria, severidad citada según ISO e informes de diagnóstico diseñados para respaldar y acelerar la toma de decisiones de los expertos.

Un servidor MCP de código abierto que convierte a los LLM en asistentes de monitorización de condición para ingenieros de fiabilidad. Su regla de diseño fundamental: el servidor se niega a adivinar. Ningún diagnóstico se infiere únicamente de nombres de archivo o parámetros estadísticos: una indicación de fallo requiere evidencia espectral coincidente. Cada afirmación de severidad cita la ISO 20816-3, y la redacción evaluativa de los informes la genera el servidor, no la improvisa el modelo. La IA orquesta el análisis y presenta la evidencia (frecuencias de fallo detectadas, patrones de fallo coincidentes, zonas de severidad), mientras que el juicio final recae en el ingeniero. También disponible como plugin de Claude Code con 8 habilidades de diagnóstico.

Véalo en Acción

Flujo de trabajo de diagnóstico completo: cargar señal → análisis espectral → detección de fallos → evaluación de severidad → generación de informes

Elija Su Camino

Inicio Rápido

Póngalo en marcha en ~3 minutos. En Windows, un solo script lo conecta todo con Claude Desktop: instala el venv, precompila las dependencias y escribe claude_desktop_config.json por usted (incluidas rutas de OneDrive / sincronización en la nube):

git clone https://github.com/LGDiMaggio/predictive-maintenance-mcp.git
cd predictive-maintenance-mcp
.\setup_claude.ps1

Reinicie Claude Desktop y luego pruebe:

"Carga real_train/OuterRaceFault_1.csv y comprueba si el rodamiento está sano."

pip install predictive-maintenance-mcp

{
  "mcpServers": {
    "predictive-maintenance": {
      "command": "/full/path/to/uvx",
      "args": ["predictive-maintenance-mcp"],
      "env": { "UV_LINK_MODE": "copy" }
    }
  }
}

Más opciones: instalar desde el código fuente · configuración para VS Code · implementación con Docker / HTTPS · uso con LLM locales (Ollama)

Benchmark

Un benchmark ciego y reproducible de precisión diagnóstica sobre el conjunto de datos público CWRU Bearing Data Center (subconjunto del extremo de accionamiento a 12 kHz: 60 registros de fallo + 4 líneas base normales). Las etiquetas de fallo nunca llegan al sistema evaluado: las señales entran bajo identificadores opacos, un evaluador separado es el único lector de etiquetas, y la ceguera, la integridad de las sumas de verificación y la determinismo se garantizan mediante pruebas de control ejecutadas por CI, no por descripciones. Los resultados se estratifican según los grados de diagnosticabilidad por registro del estudio de referencia de Smith & Randall (2015), de modo que los registros que ese estudio consideró no diagnosticables por ningún método clásico se informan por separado, en lugar de inflar o deflactar la cifra principal.

En los registros que el estudio de referencia clasifica como claramente diagnosticables (Y1+Y2, 44 registros): frecuencia de fallo característica detectada en 44/44, fallo correcto clasificado en primer lugar en 34/44 (77.3%), y 9/9 en el estrato de firma canónica (Y1). En las 4 líneas base sanas, 2 registros generaron una indicación falsa bajo el mismo criterio.

Las cifras anteriores se leen del artefacto confirmado y reejectuable (results.json) y están protegidas contra desviaciones por CI: cada valor está vinculado a su clave en el artefacto, y cualquier discrepancia hace fallar la compilación. Metodología, protocolo ciego y notas sobre benchmarking honesto: docs/benchmark-methodology.md. Reproduzca con:

python -m benchmarks.cwru all

¿Qué Puede Hacer?

Apunte la IA a una señal de vibración → obtenga la evidencia detrás del fallo — frecuencias detectadas, patrones de fallo coincidentes, severidad citada según ISO — para respaldar su decisión.

La IA no adivina: llama a 37 endpoints MCP especializados (34 herramientas + 3 prompts) que se ejecutan localmente en su máquina. Cada señal se referencia mediante un único identificador signal_id desde la carga hasta el informe. Sus datos nunca abandonan su infraestructura.

Referencia completa de endpoints, agrupados por categoría: Catálogo de herramientas.

Plugin para Claude Code

El proyecto incluye un plugin para Claude Code con habilidades específicas del dominio que se activan automáticamente durante la conversación.

/plugin marketplace add LGDiMaggio/predictive-maintenance-mcp
/plugin install predictive-maintenance@predictive-maintenance-marketplace

El plugin añade 8 habilidades que se activan automáticamente según el contexto (diagnóstico-de-rodamientos, diagnóstico-de-engranajes, cribado-rápido, generación-de-informes, detección-de-anomalías, gestión-de-señales, búsqueda-en-documentación, pronósticos), 2 agentes que ejecutan flujos de trabajo de diagnóstico en varios pasos de principio a fin y le entregan la evidencia (pipeline-de-diagnóstico, explorador-de-señales), y 3 comandos como puntos de entrada rápidos (/pm-diagnose, /pm-screen, /pm-report).

Referencia completa de habilidades, agentes y comandos: README del plugin.

Informes

Todas las herramientas de análisis generan informes HTML interactivos que puede abrir en cualquier navegador: pan, zoom y pasar el cursor para ver detalles. También admite exportaciones estructuradas a Word (.docx).

Datos de Muestra Incluidos

El proyecto incluye 20 señales reales de vibración de rodamientos de pruebas de maquinaria de producción, listas para usar sin configuración adicional: un conjunto de entrenamiento (2 líneas base sanas + 12 señales de fallo, pista interna y externa) y un conjunto de prueba (1 línea base sana + 5 señales de fallo).

Pruebe: "Carga real_train/OuterRaceFault_1.csv y diagnostica el fallo del rodamiento."

Documentación completa del conjunto de datos: data/README.md

Arquitectura

          YOU (natural language)
               │
               v
     LLM (Claude, GPT, Ollama...)
     understands intent, selects tools
               │
               v  ── Model Context Protocol ──
    ┌──────────────────────────────┐
    │    Predictive Maintenance    │
    │         MCP Server           │
    │                              │
    │  Signal Analysis    Reports  │
    │  Fault Detection    ML       │
    │  Severity Rating    RAG Docs │
    └──────────────────────────────┘
               │
               v
       YOUR DATA (stays local)
    signals · manuals · models

El código base sigue una arquitectura modular organizada en torno al estándar de diagnóstico ISO 13374 de seis bloques: adquisición de señales, procesamiento, diagnóstico, pronóstico y soporte de decisiones como subpaquetes separados. Normas implementadas: ISO 13374, ISO 20816-3, MIMOSA OSA-CBM. Detalle a nivel de módulo: Guía de arquitectura.

Decisiones de diseño clave:

• Privacidad primero — los datos brutos de vibración nunca salen de su máquina; solo los resultados calculados llegan al LLM
• Independiente del LLM — funciona con Claude, ChatGPT, Microsoft Copilot Studio o cualquier cliente compatible con MCP. Use Ollama para implementaciones totalmente aisladas de la red
• Modular — utilice solo las herramientas que necesite y amplíe con las suyas propias

Documentación

Pruebas

Más del 85 % de cobertura de pruebas, exigida como mínimo en CI, en Windows, macOS y Linux (Python 3.11 y 3.12): la cifra medida actual aparece en la insignia de codecov de arriba.

pytest                                  # run all tests
pytest --cov=src --cov-report=html      # with coverage report

Más de 20 archivos de prueba que cubren análisis de señales, detección de fallos, evaluación de severidad, modelos de ML, generación de informes, búsqueda RAG y validación con datos reales de fallos de rodamientos.

Hoja de Ruta

• 37 endpoints MCP (34 herramientas, 3 prompts) con arquitectura modular y un único identificador signal_id
• Plugin de Claude Code (8 habilidades, 2 agentes, 3 comandos)
• Más del 85 % de cobertura de pruebas exigida en CI, CI/CD en 3 plataformas
• Docker + transporte SSE/HTTP para implementación empresarial
• Búsqueda semántica de documentos (FAISS + TF-IDF)
• Benchmark de diagnóstico ciego y reproducible sobre el conjunto de datos CWRU (extensible a Paderborn)
• Umbrales de severidad personalizables
• Estimación de vida útil restante (RUL) a partir de mediciones repetidas (lineal, exponencial, Kalman)
• Análisis de tendencias y detección de inicio de degradación
• Seguimiento de múltiples señales y comparación histórica
• Transmisión en tiempo real (MQTT/Kafka)
• Panel de flota para monitorización de múltiples activos
• Integración con CMMS (SAP, Maximo, Infor)

¿Tiene ideas? Abra una discusión o cree un issue.

¿Está usando este proyecto?

Me encantaría saberlo de verdad. Tanto si lo ha ejecutado en maquinaria real como si solo ha probado los datos de muestra, escriba una línea en Discussions: una frase sobre su máquina o caso de uso es suficiente. Los comentarios del mundo real orientan directamente lo que se construye después.

Relacionado

claude-stwinbox-diagnostics — Amplía este proyecto conectando un sensor físico de borde (STEVAL-STWINBX1) a Claude mediante MCP, con Claude Skills para monitorización de condición guiada. El mismo motor de análisis, hardware real e informes pensados para operarios.

Contribuciones

Las contribuciones son bienvenidas de todos — no solo de programadores. Expertos en dominio, redactores técnicos y evaluadores son igualmente valorados. Consulta CONTRIBUTING.md para rutas adaptadas a tu perfil.

Inicio rápido: explora Issues para etiquetas good first issue o help wanted.

Citación

@software{dimaggio_predictive_maintenance_mcp_2025,
  title   = {Predictive Maintenance MCP Server},
  author  = {Di Maggio, Luigi Gianpio},
  year    = {2025},
  version = {0.13.0},
  url     = {https://github.com/LGDiMaggio/predictive-maintenance-mcp},
  doi     = {10.5281/zenodo.17611542}
}

Licencia

MIT — consulta LICENSE. Los datos de muestra son CC BY-NC-SA 4.0 (no comercial); para uso comercial, reemplázalos con tus propios datos de maquinaria.

Agradecimientos

MCP Python SDK (derivado de FastMCP) · Model Context Protocol de Anthropic · Datos de muestra de MathWorks · Desarrollo principal asistido por Claude

Un agente de IA de mantenimiento predictivo de código abierto y copiloto de monitoreo de condición — creado para apoyar a ingenieros de confiabilidad y a la comunidad de desarrolladores.