Predictive Maintenance MCP Server

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 7 diagnostic skills. It's designed to support and accelerate expert decision-making.

Quick Start

hljs language-bash

pip install predictive-maintenance-mcp

Windows — automatic setup (recommended):

Clone the repo and run the setup script — it installs the venv, pre-compiles dependencies, and writes claude_desktop_config.json automatically (handles OneDrive/cloud-sync paths too):

hljs language-powershell

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

Manual config (Windows / macOS / Linux):

Find the full path to uvx on your system (where uvx on Windows, which uvx on macOS/Linux), then add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

hljs language-json

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

Why the full path? Claude Desktop launches servers with a minimal PATH that often omits user-local tool directories (e.g. ~/.local/bin). Using the full path to uvx avoids a silent "command not found" failure. On Windows the typical path is C:\Users\<you>\.local\bin\uvx.exe.

Restart Claude Desktop. You're ready — try: "Load real_train/OuterRaceFault_1.csv and check if the bearing is healthy."

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

See It in Action

Predictive Maintenance MCP — diagnostic workflow in Claude Desktop

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.

You say	The AI does
"Is this bearing healthy?"	Loads the signal, runs spectral analysis, checks for fault patterns, classifies severity
"Generate a full diagnostic report"	Produces an interactive HTML report with charts, fault markers, and severity assessment
"Extract specs from test_pump_manual.pdf and diagnose the signal"	Reads the equipment manual, looks up the bearing model, calculates expected fault frequencies, matches them against the signal
"Train an anomaly detector on my healthy baselines, then flag anomalies"	Trains a machine learning model on normal data, scores new signals, highlights outliers

The AI doesn't guess — it calls 52 specialized MCP endpoints (46 tools, 2 resources, 4 prompts) running locally on your machine. Your data never leaves your infrastructure.

See the full endpoint list (52 MCP endpoints: 43 tools, 1 resource, 4 prompts)

Signal Acquisition (7 tools + 2 resources)

Endpoint	Type	Description
`load_signal`	Tool	Load vibration file (CSV, WAV, MAT, NPY, Parquet)
`list_signals`	Tool	Browse available signal files with metadata
`list_stored_signals`	Tool	List cached signals in memory
`get_signal_info`	Tool	Signal metadata (sampling rate, duration, stats)
`generate_test_signal`	Tool	Create synthetic signals for testing
`clear_signal` / `clear_all_signals`	Tool	Cache management
`signal://list`	Resource	Browse all signal files
`signal://read/{filename}`	Resource	Read signal metadata

Spectral & Statistical Analysis (10 tools)

Tool	Description
`analyze_fft`	Frequency spectrum with automatic peak detection
`analyze_envelope`	Envelope analysis for bearing fault detection
`analyze_statistics`	Time-domain features (RMS, kurtosis, crest factor)
`compute_power_spectral_density`	Power spectral density (Welch method)
`compute_spectrogram_stft`	Time-frequency spectrogram
`extract_features_from_signal`	17+ statistical and spectral features
`compute_envelope_spectrum_tool`	Envelope spectrum computation
`plot_signal` / `plot_spectrum` / `plot_envelope`	Visualization tools (3 tools)

Diagnostics & Health Assessment (14 tools)

Tool	Description
`calculate_bearing_characteristic_frequencies`	Compute expected fault frequencies from bearing geometry
`check_bearing_fault_peak_tool`	Detect peaks at fault frequencies
`check_bearing_faults_direct`	Multi-fault detection (inner/outer/ball/cage)
`diagnose_vibration_tool`	Integrated evidence-based diagnosis pipeline
`search_bearing_catalog`	Look up bearing specs by model number
`lookup_bearing_and_compute_tool`	Catalog lookup + frequency calculation
`evaluate_iso_20816`	Vibration severity assessment (4 severity zones)
`assess_vibration_severity`	Health classification
`train_anomaly_model`	Train novelty detection on healthy baselines
`predict_anomalies`	Score new signals for anomalies
`search_documentation`	Semantic search over equipment manuals
`read_manual_excerpt` / `extract_manual_specs`	Extract specs from PDFs (2 tools)
`list_machine_manuals`	Browse available documentation

Reporting (9 tools)

Tool	Description
`generate_fft_report`	Interactive frequency analysis report
`generate_envelope_report`	Envelope analysis with fault markers
`generate_iso_report`	Severity zone visualization
`generate_diagnostic_report_docx`	Structured Word document report
`generate_pca_visualization_report`	2D/3D anomaly projection
`generate_feature_comparison_report`	Cross-signal feature comparison
`plot_iso_20816_chart`	ISO 20816 severity zone chart
`list_html_reports` / `get_report_info`	Report management (2 tools)

Prognostics (3 tools)

Tool	Description
`estimate_rul`	Remaining Useful Life estimation (linear, exponential, Weibull, Kalman)
`analyze_signal_trend`	Trend detection on feature time series (increasing/decreasing/stable)
`detect_signal_degradation_onset`	Baseline deviation detection for early degradation warning

Decision Support (3 tools)

Tool	Description
`check_vibration_alert`	ISO 10816 vibration severity alert classification (zones A/B/C/D)
`check_custom_vibration_alert`	Custom threshold-based vibration alerting
`generate_maintenance_recommendations`	Context-aware maintenance recommendations from diagnosis

Guided Workflows (4 prompts + 2 resources)

Prompt	Description
`diagnose_bearing`	Complete bearing fault diagnostic decision tree
`diagnose_gear`	Gear fault detection workflow
`quick_diagnostic_report`	Fast health screening
`generate_iso_diagnostic_report`	ISO-compliant diagnostic report generation

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.

hljs language-shell

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

Claude Code Plugin — skills, agents, and slash commands in action

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

Skills (7) — activate automatically based on context

Skill	What it does
bearing-diagnosis	Walks through a complete bearing fault diagnostic workflow
gear-diagnosis	Gear fault detection via spectral pattern analysis
quick-screening	30-second vibration health check
report-generation	Professional HTML and Word report generation
anomaly-detection	Train and run ML-based anomaly detection models
signal-management	Load, inspect, and manage vibration signals
documentation-search	Search equipment manuals and bearing catalogs

Agents (2) — run autonomously for complex tasks

Agent	What it does
diagnostic-pipeline	End-to-end: load signal → spectral analysis → fault detection → severity assessment → report
signal-explorer	Explore and compare multiple signals, find outliers, characterize patterns

Commands (3) — quick entry points

Command	Example
`/pm-diagnose`	`/pm-diagnose bearing_signal.csv` — full fault diagnosis
`/pm-screen`	`/pm-screen bearing_signal.csv` — quick health check
`/pm-report`	`/pm-report bearing_signal.csv full` — generate all reports

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.

Report examples

Envelope Analysis Report

ISO Severity Assessment

Report Type	What it shows
Frequency spectrum	Peak detection, harmonic markers
Envelope analysis	Bearing fault frequency matching
Severity assessment	Vibration health zones (ISO 20816-3)
Word document	Full diagnostic narrative with embedded charts
PCA visualization	Multi-signal anomaly clustering
Feature comparison	Side-by-side signal feature analysis

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

hljs language-scss

          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.

Detailed module structure

hljs language-graphql

src/predictive_maintenance_mcp/
├── mcp_tools/                 # MCP endpoint registration (52 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, Weibull) & 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

Standards implemented: ISO 13374 (diagnostic architecture), ISO 20816-3 (vibration severity classification), MIMOSA OSA-CBM (condition-based maintenance framework).

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

Guide	For
Quickstart for Engineers	Get results fast, no coding required
Quickstart for Developers	Understand MCP, extend the server
Plugin README	Claude Code plugin installation and usage
HTTPS Deployment	Docker + HTTPS for enterprise environments
Ollama Guide	Use with local LLMs (fully air-gapped)
Architecture	ISO 13374 block mapping and module design
Examples	Complete diagnostic workflows
Installation	Detailed setup and troubleshooting
Contributing	How to contribute (all skill levels welcome)
Changelog	Version history

Testing

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

hljs language-bash

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

Ideas? Open a discussion or create an issue.

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

hljs language-bibtex

@software{dimaggio_predictive_maintenance_mcp_2025,
  title   = {Predictive Maintenance MCP Server},
  author  = {Di Maggio, Luigi Gianpio},
  year    = {2025},
  version = {0.8.0},
  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.

predictive-maintenance-mcp