Open-source · runs on your machine · MIT licensed

Ask Your Machines
How They're Feeling

An AI copilot for maintenance teams. Upload vibration data, ask questions in plain language, get clear diagnoses, risk levels, and actionable reports — without writing a single line of code.

pip install predictive-maintenance-mcp
PyPI version DOI Tests Coverage License MIT Python 3.11+
0
MCP Endpoints
0
Diagnostic Skills
0
% Test Coverage
100%
Local Processing
Why This Exists

Tools Turn Guesses into Evidence

Without dedicated diagnostic tools, an AI can only speculate. With them, it runs a real analysis pipeline and delivers measured, repeatable answers.

✘ Plain LLM — No Tools
“It might be a bearing fault… maybe check the alignment? I’d suggest monitoring it.”
Text-only, no real data No measurements or frequencies Not repeatable across operators
✔ With MCP Tools
“Outer-race bearing wear detected at 89.4 Hz (expected 89.8 Hz). Vibration: 4.2 mm/s — alert zone. Recommend inspection within 24 h.”
Real sensor data processed locally Measured frequencies and severity Consistent, auditable results

Same AI, different outcomes. The tools make the difference.

What Can You Do With It

Talk to Your Data, Get Answers You Can Act On

The assistant runs the full analysis pipeline on your machine and explains results in language your team understands.

💬“Is this bearing healthy?”
Loads your data, checks fault patterns, estimates severity, and returns a clear health verdict with supporting evidence.
💬“Generate a report for my supervisor”
Creates a manager-friendly HTML report with key charts, risk level, findings summary, and recommended next actions.
💬“Use the pump manual to diagnose this signal”
Reads equipment documentation and bearing catalog specs, then matches expected fault signatures against your measured data.
💬“Learn what ‘normal’ looks like for these machines”
Trains on healthy baseline runs and flags unusual patterns in future signals — before they become failures.
Get Started

From Install to Insight in Five Minutes

1

Install

pip install predictive-maintenance-mcp — connect to Claude Desktop, VS Code, or any MCP client.

2

Ask

“Load OuterRaceFault_1.csv and check if the bearing is healthy.”

3

Act

Get a clear diagnosis, confidence signals, risk classification, and recommended next steps.

Live Preview

What a Conversation Looks Like

Claude Desktop — PM-MCP Connected
You
Is this pump safe to run for the next shift?
Assistant
I ran a vibration severity assessment on the latest data. The RMS velocity is 4.2 mm/s, placing this pump in the Alert zone. I recommend planning an inspection within 24 hours and reducing load if possible.
You
What's the most likely fault? Create a report for my supervisor.
Assistant
The fault signature is consistent with outer-race bearing wear on the drive-end side. I’ve generated an HTML report with key charts and a recommended action plan — saved to reports/.
See It in Action

Real Workflows, Not Marketing Slides

Watch the full diagnostic flow — from raw signal to professional report — in Claude Desktop and Claude Code.

💬 Claude Desktop

Predictive Maintenance MCP — diagnostic workflow in Claude Desktop

Load signal → spectral analysis → fault detection → severity assessment → report

🔌 Claude Code Plugin

Claude Code Plugin — skills and slash commands in action

Domain skills activate automatically · slash commands for quick diagnostics

Capabilities

Everything You Need for Machine Diagnostics

From raw vibration files to maintenance decisions — all running locally on your infrastructure.

🔍

Frequency Analysis

Decompose signals into frequency components with automatic peak detection, harmonic identification, and clear visualizations.

⚙️

Early Fault Detection

Highlight subtle impact patterns that indicate early bearing or gear wear — even when the raw signal looks normal.

🚦

Risk Classification

Automatic severity zones so teams know immediately what needs urgent attention and what can wait.

🤖

Anomaly Detection

Train on healthy baselines, then automatically flag unusual signals. Machine learning models with zero-code setup.

📋

Clear Reports

Generate HTML reports with interactive charts and structured Word documents. Designed for engineers, operators, and management.

📖

Manual-Aware Diagnosis

Search equipment manuals and bearing catalogs. Extract specs from PDFs and cross-check against measured data automatically.

📈

Multi-Format Ingestion

Load vibration data from CSV, WAV, MAT, NPY, and Parquet files. Automatic sampling rate detection and metadata extraction.

🧠

Action Recommendations

Evidence-based maintenance suggestions with confidence levels. No guessing — every recommendation cites its source data.

🔌

Extensible & Open

Plugin architecture for custom signal processors and report formats. Works with Claude, ChatGPT, Ollama, or any MCP-compatible client.

Claude Code Plugin

Automate Diagnostics From Your Editor

7 skills, 2 autonomous agents, 3 slash commands — works inside Claude Code.

/plugin marketplace add LGDiMaggio/predictive-maintenance-mcp
🎯

7 Domain Skills

Bearing diagnosis, gear analysis, quick screening, report generation, anomaly detection, signal management, and documentation search.

🤖

2 Autonomous Agents

diagnostic-pipeline: End-to-end workflow from signal to report. signal-explorer: Compare and characterize multiple signals.

3 Slash Commands

/pm-diagnose for bearing diagnosis, /pm-screen for quick health checks, /pm-report for instant reports.

Under the Hood

Your Data Never Leaves Your Machine

Raw vibration files stay local. Only computed results (severity scores, fault types) flow to the AI for interpretation.

YOU (natural language) | v LLM (Claude / GPT / Ollama) | Model Context Protocol v +----------------------------------+ | Predictive Maintenance MCP | | | | data_ingestion | | signal_processing | | diagnostics | | prognostics | | decision_support | +----------------------------------+ | v YOUR DATA (always local) signals · manuals · models

🔒 Privacy-First

Raw vibration data is processed entirely on your machine. Only computed results flow to the LLM — never raw waveforms.

🌐 Works With Any AI

Claude, ChatGPT, Microsoft Copilot Studio, or Ollama for fully air-gapped deployments. Any MCP client works.

🏗 Structured Pipeline

Six-stage diagnostic flow: ingest → process → detect → assess → predict → recommend. Each stage is independent and testable.

🧩 Extensible by Design

Use only the tools you need. Plugin architecture for custom signal processors, diagnostics, and report formats.

Who It's For

Engineers & Developers

Whether you maintain machines or build AI tools — this is your starting point.

🔧

Reliability & Maintenance Engineers

Diagnose machine health through conversation. No signal-processing expertise required.

  • Screen machine health by asking simple questions
  • Identify likely fault families from real vibration data
  • Generate shareable reports for management
  • Follow guided diagnostic workflows
Engineer Quick Start →
💻

AI & Software Developers

Study real MCP tool architecture and build industrial copilots on a production-ready foundation.

  • Learn MCP tool design patterns from a real project
  • Extend with custom tools and datasets
  • Build reusable industrial AI workflows
  • Install the Claude Code plugin for fast iteration
Developer Quick Start →
Ready to Try

Real Bearing Data Included

20 vibration signals from production machinery — install and start diagnosing immediately.

Production Bearing Fault Dataset

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

20
Signals
3
Fault Types
3
Healthy Baselines
Try: “Load OuterRaceFault_1.csv and diagnose the bearing.”
Questions

Frequently Asked

An open-source tool that lets you ask an AI assistant about your machine's vibration data and get real, evidence-based maintenance answers — running entirely on your computer.
No. Raw vibration files are processed locally. Only computed summaries (severity scores, fault classifications) are sent to the AI for interpretation. Use Ollama for a fully air-gapped setup.
Any MCP-compatible client: Claude Desktop, VS Code with Copilot, ChatGPT (via MCP bridge), Microsoft Copilot Studio, or local models with Ollama.
No. Ask questions in plain language like “Is this bearing healthy?” The AI handles the analysis pipeline and explains results in everyday terms.
Outer race, inner race, and rolling element bearing defects; gear mesh issues; general unbalance and misalignment. The system uses frequency analysis, envelope detection, and trained anomaly models.
No. It's a screening and decision-support tool that helps prioritize and communicate. Critical decisions should always be validated by qualified reliability engineers.
Yes. The plugin architecture supports custom signal processors, diagnostic logic, and report formats. See the Developer Quick Start for details.
Documentation

Guides for Every Background

Related

Hardware Extension

claude-stwinbox-diagnostics

Connects a physical edge sensor (STEVAL-STWINBX1) to Claude via MCP. Same analysis engine, real hardware, operator-friendly reports.

Citation

Cite This Project

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