Predictive Maintenance MCP

Predictive Maintenance MCP Server

Dê ao seu assistente de IA diagnósticos de vibração baseados em evidências — detecção de falhas em máquinas, severidade citada por ISO e relatórios diagnósticos criados para apoiar e acelerar a tomada de decisão de especialistas.

Um servidor MCP de código aberto que transforma LLMs em assistentes de monitoramento de condição para engenheiros de confiabilidade. Sua regra de design central: o servidor se recusa a adivinhar. Nenhum diagnóstico é jamais inferido apenas por nomes de arquivo ou parâmetros estatísticos — uma indicação de falha exige evidência espectral correspondente. Toda alegação de severidade cita a ISO 20816-3, e a redação avaliativa nos relatórios é de autoria do servidor, não improvisada pelo modelo. A IA orquestra a análise e apresenta as evidências — frequências de falha detectadas, padrões de falha correspondentes, zonas de severidade — enquanto o julgamento final permanece com o engenheiro. Também disponível como um plugin para Claude Code com 8 habilidades diagnósticas.

Veja em Ação

Fluxo diagnóstico completo: carregar sinal → análise espectral → detecção de falhas → avaliação de severidade → geração de relatório

Escolha Seu Caminho

Início Rápido

Comece a funcionar em ~3 minutos. No Windows, um script configura tudo no Claude Desktop — ele instala o venv, pré-compila dependências e escreve o claude_desktop_config.json para você (incluindo caminhos de OneDrive / sincronização em nuvem):

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

Reinicie o Claude Desktop e tente:

"Carregue real_train/OuterRaceFault_1.csv e verifique se o rolamento está saudável."

pip install predictive-maintenance-mcp

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

Mais opções: instalar a partir do código-fonte · configuração no VS Code · implantação Docker / HTTPS · usar com LLMs locais (Ollama)

Benchmark

Um benchmark de precisão de diagnóstico cego e reproduzível no conjunto de dados público CWRU Bearing Data Center (subconjunto de acionamento de 12 kHz: 60 registros de falha + 4 linhas de base normais). Os rótulos de falha nunca chegam ao sistema testado — os sinais entram sob ids opacos, um avaliador separado é o único leitor de rótulos, e a cegueira, a integridade de checksum e a determinismo são garantidos por testes de guarda executados em CI, não por prosa. Os resultados são estratificados pelos graus de diagnosticabilidade por registro do estudo de referência Smith & Randall (2015), de modo que os registros que esse estudo considerou não diagnosticáveis por qualquer método clássico são relatados separadamente, em vez de inflar ou deflacionar o número principal.

Em registros que o estudo de referência classifica como claramente diagnosticáveis (Y1+Y2, 44 registros): frequência característica de falha detectada em 44/44, falha correta classificada em primeiro lugar em 34/44 (77.3%), e 9/9 no estrato de assinatura clássica (Y1). Nas 4 linhas de base saudáveis, 2 registros geraram indicação falsa sob o mesmo critério.

Os números acima são lidos do artefato confirmado e re-executável (results.json) e protegidos contra desvios por CI: cada valor está vinculado à sua chave no artefato, e uma discrepância falha a compilação. Metodologia, protocolo cego e notas de benchmark honesto: docs/benchmark-methodology.md. Reproduza com:

python -m benchmarks.cwru all

O Que Ele Pode Fazer?

Aponte a IA para um sinal de vibração → obtenha as evidências por trás da falha — frequências detectadas, padrões de falha correspondentes, severidade citada por ISO — para apoiar sua decisão.

A IA não adivinha — ela chama 37 endpoints MCP especializados (34 ferramentas + 3 prompts) executados localmente na sua máquina. Cada sinal é referenciado por um único identificador signal_id do carregamento ao relatório. Seus dados nunca saem da sua infraestrutura.

Referência completa de endpoints, agrupados por categoria: Catálogo de Ferramentas.

Plugin para Claude Code

O projeto inclui um plugin para Claude Code com habilidades específicas de domínio que ativam automaticamente durante a conversa.

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

O plugin adiciona 8 habilidades que ativam automaticamente com base no contexto (diagnóstico-de-rolamentos, diagnóstico-de-engrenagens, triagem-rápida, geração-de-relatórios, detecção-de-anomalias, gerenciamento-de-sinais, busca-em-documentação, prognósticos), 2 agentes que executam fluxos diagnósticos multi-etapa de ponta a ponta e entregam a você as evidências (pipeline-de-diagnóstico, explorador-de-sinais) e 3 comandos para pontos de entrada rápidos (/pm-diagnose, /pm-screen, /pm-report).

Referência completa de habilidades, agentes e comandos: Leia-me do Plugin.

Relatórios

Todas as ferramentas de análise geram relatórios HTML interativos que você pode abrir em qualquer navegador — pane, zoom, passe o mouse para obter detalhes. Também suporta exportações estruturadas em Word (.docx).

Dados de Amostra Incluídos

O projeto acompanha 20 sinais reais de vibração de rolamentos de testes de máquinas de produção — prontos para uso imediato: um conjunto de treinamento (2 linhas de base saudáveis + 12 sinais de falha, pista interna e externa) e um conjunto de teste (1 linha de base saudável + 5 sinais de falha).

Tente: "Carregue real_train/OuterRaceFault_1.csv e diagnostique a falha do rolamento."

Documentação completa do conjunto de dados: data/README.md

Arquitetura

          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

O código-fonte segue uma arquitetura modular organizada em torno do padrão de diagnóstico ISO 13374 Six-Block — aquisição de sinal, processamento, diagnóstico, prognóstico e suporte à decisão como subpacotes separados. Padrões implementados: ISO 13374, ISO 20816-3, MIMOSA OSA-CBM. Detalhes no nível de módulo: Guia de arquitetura.

Principais escolhas de design:

• Privacidade em primeiro lugar — os dados brutos de vibração nunca saem da sua máquina; apenas resultados calculados fluem para o LLM
• Agnóstico de LLM — funciona com Claude, ChatGPT, Microsoft Copilot Studio ou qualquer cliente compatível com MCP. Use Ollama para implantações totalmente isoladas
• Modular — use apenas as ferramentas que você precisa, estenda com as suas próprias

Documentação

Testes

Cobertura de testes acima de 85%, garantida como mínimo de CI, em Windows, macOS e Linux (Python 3.11 e 3.12) — o valor atual medido está no selo codecov acima.

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

Mais de 20 arquivos de teste cobrindo análise de sinal, detecção de falhas, avaliação de severidade, modelos de ML, geração de relatórios, busca RAG e validação com dados reais de falhas em rolamentos.

Roadmap

• 37 endpoints MCP (34 ferramentas, 3 prompts) com arquitetura modular e um único identificador signal_id
• Plugin para Claude Code (8 habilidades, 2 agentes, 3 comandos)
• Cobertura de testes acima de 85% garantida em CI, CI/CD em 3 plataformas
• Docker + transporte SSE/HTTP para implantação corporativa
• Busca semântica em documentos (FAISS + TF-IDF)
• Benchmark diagnóstico cego e reproduzível no conjunto de dados CWRU (extensível a Paderborn)
• Limiares de severidade personalizáveis
• Estimativa de vida útil remanescente (RUL) a partir de medições repetidas (linear, exponencial, Kalman)
• Análise de tendência e detecção de início de degradação
• Tendência multi-sinal e comparação histórica
• Streaming em tempo real (MQTT/Kafka)
• Painel para frota com monitoramento de múltiplos ativos
• Integração com CMMS (SAP, Maximo, Infor)

Ideias? Abra uma discussão ou crie uma issue.

Você está usando isso?

Eu realmente adoraria saber. Se você executou em máquinas reais ou apenas testou com os dados de amostra, deixe uma mensagem em Discussões — uma frase sobre sua máquina ou caso de uso é suficiente. O feedback do mundo real influencia diretamente o que será construído em seguida.

Relacionados

claude-stwinbox-diagnostics — Estende este projeto conectando um sensor de borda físico (STEVAL-STWINBX1) ao Claude via MCP, com skills do Claude para monitoramento de condição guiado. Mesmo mecanismo de análise, hardware real, relatórios amigáveis ao operador.

Contribuição

Contribuições são bem-vindas de todos — não apenas programadores. Especialistas de domínio, redatores técnicos e testadores são igualmente valorizados. Veja CONTRIBUTING.md para caminhos adaptados ao seu perfil.

Início rápido: navegue por Issues com os rótulos good first issue ou help wanted.

Citação

@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}
}

Licença

MIT — veja LICENSE. Os dados de exemplo são CC BY-NC-SA 4.0 (não comerciais); para uso comercial, substitua pelos seus próprios dados de máquinas.

Agradecimentos

MCP Python SDK (descendente do FastMCP) · Model Context Protocol da Anthropic · Dados de exemplo do MathWorks · Desenvolvimento principal auxiliado pelo Claude

Um agente de IA de manutenção preditiva de código aberto e copiloto de monitoramento de condições — criado para apoiar engenheiros de confiabilidade e a comunidade de desenvolvedores.