Predictive Maintenance Server

Python 3.11+ DOI Tests codecov License: MIT

Give any AI assistant the ability to analyze vibration data, detect machinery faults, and generate professional diagnostic reports — through natural conversation.

An open-source MCP server and predictive maintenance AI agent that turns LLMs into condition monitoring assistants. Engineers describe what they need in plain language; the AI calls the right analysis tools and delivers results — bearing fault detection, risk assessment, anomaly detection, and remaining useful life estimation. Also available as a Claude Code plugin with 8 diagnostic skills. It's designed to support and accelerate expert decision-making.

Who is this for?

• Reliability & maintenance engineers who want fast vibration diagnostics in plain language — no coding required. It augments and accelerates expert judgment; it doesn't replace it.
• Developers & industrial-AI practitioners who want to expose predictive-maintenance workflows as MCP tools and build on top of them.
• Researchers & students working on bearing fault diagnosis, condition monitoring, or MCP / agent tooling.

Quick Start

Get running in ~3 minutes. On Windows, one script wires everything into Claude Desktop — it installs the venv, pre-compiles dependencies, and writes claude_desktop_config.json for you (OneDrive / cloud-sync paths included):

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

Restart Claude Desktop, then try:

"Load real_train/OuterRaceFault_1.csv and check if the bearing is healthy."

pip install predictive-maintenance-mcp

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

More options: install from source · VS Code setup · Docker / HTTPS deployment · use with local LLMs (Ollama)

See It in Action

Full diagnostic workflow: load signal → spectral analysis → fault detection → severity assessment → report generation

What Can It Do?

Upload a vibration signal → get a professional diagnosis through conversation.

The AI doesn't guess — it calls 36 specialized MCP endpoints (33 tools + 3 prompts) running locally on your machine. Every signal is referenced by a single signal_id handle from load to report. Your data never leaves your infrastructure.

Claude Code Plugin

The project includes a plugin for Claude Code with domain-specific skills that activate automatically during conversation. Install it and Claude gains guided diagnostic workflows, autonomous agents, and quick commands.

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

Claude Code plugin: domain skills activate automatically, slash commands for quick diagnostics

Skills (8) — activate automatically based on context

Agents (2) — run autonomously for complex tasks

Commands (3) — quick entry points

Reports

All analysis tools generate interactive HTML reports you can open in any browser — pan, zoom, hover for details. Also supports structured Word (.docx) exports.

Sample Data Included

The project ships with 20 real bearing vibration signals from production machinery tests — ready to use out of the box.

• Training set: 2 healthy baselines + 12 fault signals (inner race, outer race)
• Test set: 1 healthy baseline + 5 fault signals

Try: "Load real_train/OuterRaceFault_1.csv and diagnose the bearing fault."

Full dataset documentation: data/README.md

Architecture

          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

The codebase follows a modular architecture organized around the ISO 13374 Six-Block Diagnostic standard — signal acquisition, processing, diagnostics, prognostics, and decision support as separate sub-packages.

src/predictive_maintenance_mcp/
├── mcp_tools/                 # MCP endpoint registration (36 MCP endpoints)
│   ├── acquisition_tools.py   # Signal loading & management
│   ├── analysis_tools.py      # Spectral & statistical analysis
│   ├── diagnostics_tools.py   # Fault detection, ML, document search
│   ├── report_tools.py        # HTML/DOCX report generation
│   ├── prompts.py             # Guided diagnostic workflows
│   └── _utils.py              # Shared utilities
├── signal_acquisition/        # Multi-format loaders (CSV, MAT, WAV, NPY, Parquet)
├── signal_processing/         # Spectral analysis & feature extraction
├── diagnostics/               # Bearing/gear analysis, ISO standards
├── decision_support/          # Evidence-based diagnosis pipeline
├── prognostics/               # RUL estimation (linear, exponential, Kalman) & trend analysis
├── rag.py                     # Document indexing & search (FAISS/TF-IDF)
├── models.py                  # Pydantic data models
├── server.py                  # FastMCP server entry point
└── config.py                  # Configuration management

Key design choices:

• Privacy-first — raw vibration data never leaves your machine; only computed results flow to the LLM
• LLM-agnostic — works with Claude, ChatGPT, Microsoft Copilot Studio, or any MCP-compatible client. Use Ollama for fully air-gapped deployments
• Modular — use only the tools you need, extend with your own

Documentation

Testing

86% test coverage across Windows, macOS, and Linux (Python 3.11 & 3.12).

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

20+ test files covering signal analysis, fault detection, severity assessment, ML models, report generation, RAG search, and real bearing fault data validation.

Roadmap

• 36 MCP endpoints (33 tools, 3 prompts) with modular architecture and a single signal_id handle
• Claude Code plugin (8 skills, 2 agents, 3 commands)
• 86% test coverage, CI/CD on 3 platforms
• Docker + SSE/HTTP transport for enterprise deployment
• Semantic document search (FAISS + TF-IDF)
• Customizable severity thresholds
• Remaining useful life (RUL) estimation from repeated measurements (linear, exponential, Kalman)
• Trend analysis and degradation onset detection
• Multi-signal trending and historical comparison
• Real-time streaming (MQTT/Kafka)
• Fleet dashboard for multi-asset monitoring
• CMMS integration (SAP, Maximo, Infor)

Ideas? Open a discussion or create an issue.

Are you using this?

I'd genuinely love to know. Whether you ran it on real machinery or just tried the sample data, drop a line in Discussions — one sentence about your machine or use case is enough. Real-world feedback directly shapes what gets built next.

Related

claude-stwinbox-diagnostics — Extends this project by connecting a physical edge sensor (STEVAL-STWINBX1) to Claude via MCP, with Claude Skills for guided condition monitoring. Same analysis engine, real hardware, operator-friendly reports.

Contributing

Contributions welcome from everyone — not just programmers. Domain experts, technical writers, and testers are equally valued. See CONTRIBUTING.md for paths tailored to your background.

Quick start: browse Issues for good first issue or help wanted labels.

Citation

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

License

MIT — see LICENSE. Sample data is CC BY-NC-SA 4.0 (non-commercial); for commercial use, replace with your own machinery data.

Acknowledgments

FastMCP framework · Model Context Protocol by Anthropic · Sample data from MathWorks · Core development assisted by Claude

An open-source predictive maintenance AI agent and condition monitoring copilot — built to support reliability engineers and the developer community.