Predictive Maintenance

You can run a self-contained Predictive Maintenance MCP Server locally to empower LLMs with industrial diagnostics, vibration analysis, and predictive maintenance workflows. It connects to your machine data, manuals, and processing tools to produce interactive reports and AI-assisted insights without sending data to external services.

How to use

Start by configuring an MCP client to connect to your local MCP server. The server provides direct data access to vibration signals and machine manuals, along with a suite of processing tools for FFT analysis, envelope analysis, ISO 20816-3 compliance checks, and ML-based anomaly detection. You can ask the system to diagnose bearing faults, generate professional HTML reports, extract bearing specifications from manuals, and train or run anomaly detectors on healthy baselines. Use natural language prompts to guide the analysis workflow, select the data you want to examine, and request the exact type of report you need.

Typical workflows you can run include:

• Diagnose bearing faults from a vibration signal and retrieve fault frequencies (BPFO, BPFI, BSF, FTF).
• Generate an envelope report with bearing fault markers and export an interactive HTML report.
• Evaluate a signal against ISO 20816-3 and obtain a zone-based visualization and recommendations.
• Extract machine-bearing specs from manuals and compute bearing fault frequencies from RPM data, then diagnose accordingly.
• Train and validate an ML anomaly detector using healthy baseline signals, then run predictions on new signals.

How to install

Prerequisites: you need Python and a supported shell. You will also use a Python virtual environment created by the installer. Follow these exact steps to get started.

# 1. Clone the MCP server repository
git clone https://github.com/LGDiMaggio/predictive-maintenance-mcp.git
cd predictive-maintenance-mcp

# 2. Run automated setup to create a virtual environment
python setup_venv.py

# 3. Activate the environment
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/macOS

# 4. Verify installation
python validate_server.py

Configuration

To connect your MCP client (Claude Desktop or VS Code) to the local server, you provide a stdio command that launches the Python process inside your virtual environment and points to the main server script.

{
  "mcpServers": {
    "pred_maint_claude": {
      "command": "C:/path/to/predictive-maintenance-mcp/.venv/Scripts/python.exe",
      "args": ["C:/path/to/predictive-maintenance-mcp/src/machinery_diagnostics_server.py"]
    }
  }
}

If you prefer to connect through VS Code, use the equivalent server entry under the servers section with a POSIX-compatible path style on Linux/macOS or Windows style on Windows.

{
  "servers": {
    "pred_maint_vscode": {
      "command": "/path/to/predictive-maintenance-mcp/.venv/bin/python",
      "args": ["/path/to/predictive-maintenance-mcp/src/machinery_diagnostics_server.py"]
    }
  }
}

Notes and troubleshooting

• All data and reports are generated locally. No data leaves your machine unless you explicitly export it. • If you change the project path, update the absolute paths in the MCP config blocks above. • Restart the MCP client after updating the configuration to apply the new server connection. • If you encounter issues, run the server in a terminal to see real-time logs and verify that the virtual environment is active.

Usage patterns and examples

Example prompts you can use once the server is connected:

• Diagnose bearing fault in real_train/OuterRaceFault_1.csv and return fault frequencies.
• Generate envelope report for real_train/OuterRaceFault_1.csv and save to reports/
• Evaluate real_train/OuterRaceFault_1.csv against ISO 20816-3 and display the zone visualization.
• Extract bearing specs from test_pump_manual.pdf, calculate fault frequencies at 1475 RPM, and diagnose the signal accordingly.

Security and data handling

The MCP server is designed to be local-first, keeping data on your machine. When you use it with an LLM client, ensure that the client is trusted and that your machine is secured. Do not expose the local MCP endpoints to untrusted networks.

Troubleshooting

If the server fails to start, confirm you are in the correct virtual environment, verify Python paths in the configuration blocks, and check for missing dependencies. Re-run the activation step and re-run the installer if necessary.

Examples and datasets

The server ships with a sample dataset of 21 real bearing vibration signals, including healthy baselines and inner/outer race faults, to demonstrate the end-to-end workflow from data ingestion to report generation.

Available tools

analyze_fft

FFT spectrum analysis with automatic peak detection to identify dominant frequencies in vibration data.

analyze_envelope

Envelope analysis to detect bearing faults via modulation and fault frequencies.

analyze_statistics

Time-domain indicators such as RMS, Crest Factor, and Kurtosis for quick signal characterization.

evaluate_iso_20816

ISO 20816-3 vibration severity assessment with zone visualization and recommendations.

diagnose_bearing

Guided 6-step bearing diagnostic workflow to determine fault type and location.

diagnose_gear

Evidence-based gear fault diagnostic workflow.

extract_features_from_signal

Extract 17+ statistical features from vibration data for ML modeling.

train_anomaly_model

Train unsupervised/semisupervised anomaly detection models on healthy baselines with optional tuning.

predict_anomalies

Detect anomalies in new signals with confidence scores.

generate_fft_report

Create an interactive FFT report in HTML with peak tables.

generate_envelope_report

Create an envelope analysis report with bearing fault markers in HTML.

generate_iso_report

Generate an ISO-compliant report with vibration zone visualization.

list_html_reports

List all generated HTML reports with metadata.

get_report_info

Fetch report details without loading full HTML content.

list_machine_manuals

List available machine manuals (PDF/TXT) for context.

extract_manual_specs

Extract bearings, RPM, and power specs from manuals with caching.

calculate_bearing_characteristic_frequencies

Compute BPFO, BPFI, BSF, and FTF from bearing geometry and RPM.

read_manual_excerpt

Read excerpts from a machine manual with configurable page limit.

search_bearing_catalog

Search local bearing catalog for geometry and specs.

list_signals

Browse available vibration signal files with metadata.

generate_test_signal

Create synthetic signals for testing analysis workflows.