A Model Context Protocol server that brings industrial machinery diagnostics directly to LLMs like Claude, enabling AI-powered vibration analysis, bearing fault detection, and predictive maintenance workflows all through natural conversation.

🔧 From Vibration Data and Machine Manuals to Actionable Insights: Transform raw sensor data into reports with ISO compliance checks, FFT analysis, envelope analysis and ML anomaly detection. PdM workflows supported by LLMs.

• ✨ What Makes This Special
• 🔬 Proof of Concept & Community Invitation
• 🎬 Quick Examples
• 🚀 Installation
• Configuration
• 🔧 Available Tools & Resources
• Architecture
• 📊 Sample Dataset
• 💡 Usage Examples
• 📊 Professional Reports
• Documentation
• Debugging
• 🧪 Testing
• 🛠️ Development
• 🚀 Roadmap & Recent Updates
• License
• Citation
• Acknowledgments
• Support

• 🎯 Real Bearing Fault Data Included - 20 production-quality vibration signals from real machinery tests (3 healthy, 17 faulty)

• 📊 Professional HTML Reports - Interactive Plotly visualizations with automatic peak detection and frequency markers

• 🤖 ML Anomaly Detection - Train unsupervised/semi-supervised models (OneClassSVM/LOF) on healthy baselines with optional hyperparameter tuning

• 📏 ISO 20816-3 Compliance - Industry-standard vibration severity assessment built-in

• 🔍 Advanced Diagnostics - FFT spectrum analysis, envelope analysis for bearing faults, time-domain feature extraction

  Example analysis

  

• 🚀 Zero Configuration - Works out of the box with sample data, auto-detects sampling rates from metadata

This is a Proof of Concept (PoC) - a demonstration of feasibility showing how LLMs can be empowered with industrial diagnostics capabilities through the Model Context Protocol.

• ✅ Real vibration data integration - 20 bearing fault signals with metadata (train: 14, test: 6)
• ✅ Professional analysis workflows - FFT spectrum, envelope analysis, ISO 20816-3 compliance
• ✅ ML anomaly detection - Semi-supervised learning with hyperparameter tuning
• ✅ Metadata-driven auto-detection - Sampling rates and signal units from JSON files
• ✅ Interactive HTML reports - Plotly visualizations with automatic peak detection
• ✅ Natural language interface - Complex diagnostics through conversational AI

This PoC demonstrates the potential. Now we need your expertise to make it production-ready.

How You Can Help:

• 📊 Add More Data - Real-world vibration datasets from different machines/sensors/industries
• 🔧 Expand Diagnostics - Gear fault detection, pump cavitation, motor electrical faults, misalignment
• 🤖 Improve ML - Deep learning approaches, advanced anomaly models, real-time streaming analysis
• 🌍 Internationalization - Multi-language support, regional standards workflows (VDI, GB)
• 📖 Documentation - Tutorials, case studies, industrial validation, best practices
• 🐛 Testing - Edge cases, validation with ground truth data, cross-validation studies

Get Involved:

• 🐛 Report issues: GitHub Issues
• 💡 Suggest features: Discussions
• 🔀 Submit PRs: See CONTRIBUTING.md
• 💬 Join the conversation: LinkedIn

Why This Matters:

Predictive maintenance is critical for Industry 4.0. Complex diagnostic and maintenance workflows can be integrated with LLMs to augment human engineering work when proper context and tools are provided. Through the Model Context Protocol (MCP), we bridge LLM reasoning capabilities with specialized diagnostic tools, enabling democratized access to expert-level machinery diagnostics and making industrial AI more accessible to engineers worldwide.

Generate envelope report for real_train/OuterRaceFault_1.csv

Result: AI automatically:

1. Detects sampling rate from metadata (97,656 Hz)
2. Applies bandpass filter (500-5000 Hz)
3. Generates interactive HTML report with bearing fault frequencies marked
4. Identifies outer race fault at ~81 Hz with harmonics
5. Saves report to reports/envelope_OuterRaceFault_1_*.html

Evaluate real_train/OuterRaceFault_1.csv against ISO 20816-3 standard

Result:

• RMS velocity: 4.5 mm/s → Zone B (Acceptable for long-term operation)
• Interactive HTML report with zone visualization
• Compliance assessment and recommendations

1. Extract specifications from test_pump_manual.pdf
2. Calculate bearing frequencies for SKF 6205-2RS at 1475 RPM
3. Diagnose bearing fault in signal_from_pump.csv using calculated frequencies

Result: Complete zero-knowledge diagnosis:

• Extracts: Drive end bearing SKF 6205-2RS, operating speed 1475 RPM
• Calculates: BPFO=85.20 Hz, BPFI=136.05 Hz, BSF=101.32 Hz
• Diagnoses: Outer race fault detected with 3 harmonics

📚 More examples: See Usage Examples section below or EXAMPLES.md for complete workflows

Resources provide direct read access for Claude to examine data:

Tools perform computations and generate outputs:

The system follows a hybrid MCP architecture combining Resources (direct data access) and Tools (computational processing):

┌─────────────────────────────────────────────────────────────┐
│                    CLAUDE / LLM CLIENT                      │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                   MCP SERVER (FastMCP)                      │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  RESOURCES (Direct Data Access)                      │  │
│  │  ┌────────────────────────────────────────────────┐  │  │
│  │  │  Vibration Signals                             │  │  │
│  │  │  • signal://list                               │  │  │
│  │  │  • signal://read/{filename}                    │  │  │
│  │  └────────────────────────────────────────────────┘  │  │
│  │  ┌────────────────────────────────────────────────┐  │  │
│  │  │  Machine Manuals                               │  │  │
│  │  │  • manual://list                               │  │  │
│  │  │  • manual://read/{filename}                    │  │  │
│  │  └────────────────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  TOOLS (Analysis & Processing)                       │  │
│  │  • FFT, Envelope, ISO 20816-3                        │  │
│  │  • ML Anomaly Detection                              │  │
│  │  • Report Generation (HTML)                          │  │
│  │  • Manual Spec Extraction                            │  │
│  │  • Bearing Frequency Calculation                     │  │
│  │  • Bearing Catalog Search                            │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────┬────────────────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        ▼                         ▼
┌──────────────────┐   ┌──────────────────────────────────┐
│  SIGNAL ANALYSIS │   │  DOCUMENT READER MODULE          │
│  MODULE          │   │  ┌────────────┐  ┌────────────┐  │
│  • FFT Engine    │   │  │ PDF Extract│  │ ISO Formulas│  │
│  • Envelope      │   │  │ (PyPDF2)   │  │ BPFO/BPFI   │  │
│  • Filters       │   │  └────────────┘  └────────────┘  │
│  • Statistics    │   │  ┌─────────────────────────────┐  │
│  • ML Models     │   │  │  Bearing Catalog DB         │  │
│  • Plotly Charts │   │  │  • 20+ ISO bearings         │  │
│                  │   │  └─────────────────────────────┘  │
└────────┬─────────┘   └────────┬─────────────────────────┘
         │                      │
         ▼                      ▼
┌─────────────────────────────────────────────────────────────┐
│                   LOCAL FILE SYSTEM                         │
│  ┌──────────────────────┐   ┌──────────────────────────┐   │
│  │  data/signals/       │   │  resources/              │   │
│  │  ├── real_train/     │   │  ├── machine_manuals/    │   │
│  │  ├── real_test/      │   │  ├── bearing_catalogs/   │   │
│  │  └── samples/        │   │  ├── datasheets/         │   │
│  └──────────────────────┘   │  └── cache/ (auto)       │   │
│  ┌──────────────────────┐   └──────────────────────────┘   │
│  │  reports/            │   ┌──────────────────────────┐   │
│  │  • FFT reports       │   │  models/                 │   │
│  │  • Envelope reports  │   │  • Trained ML models     │   │
│  │  • ISO reports       │   │  • Scalers, PCA          │   │
│  └──────────────────────┘   └──────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Key Features:

• ✅ 4 MCP Resources - Direct read access to signals and manuals
• ✅ 25+ MCP Tools - Complete diagnostic workflow
• ✅ Hybrid Architecture - Resources for reading, Tools for processing
• ✅ Local-First - All data stays on your machine (privacy-preserving)

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

# 2. Run automated setup
python setup_venv.py

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

# 4. Verify installation
python validate_server.py

📖 Detailed Installation Guide: See INSTALL.md for troubleshooting, Claude Desktop setup, and developer instructions.

git clone https://github.com/LGDiMaggio/predictive-maintenance-mcp.git
cd predictive-maintenance-mcp
pip install -e .

Add to your Claude Desktop config:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

📋 Example config: See claude_desktop_config_PYTHON_VENV.json for a complete example

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

Important Notes:

• Replace C:/path/to/predictive-maintenance-mcp with your actual project path
• Use absolute paths for both command and args
• On macOS/Linux, use .venv/bin/python instead of .venv/Scripts/python.exe
• Forward slashes (/) work on all platforms, including Windows

After configuration, restart Claude Desktop completely.

Add to your MCP configuration (.vscode/mcp.json or user settings):

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

Adjust paths according to your system (use .venv/Scripts/python.exe on Windows)

The server includes 20 real bearing vibration signals from production machinery:

Training Set (14 signals):

• ✅ 2 Healthy Baselines - Normal operation data
• 🔴 7 Inner Race Faults - Variable load conditions
• ⚠️ 5 Outer Race Faults - Various severity levels

Test Set (6 signals):

• ✅ 1 Healthy Baseline - Validation data
• 🔴 2 Inner Race Faults - Test conditions
• ⚠️ 3 Outer Race Faults - Test conditions

Note: Sampling rates and durations vary by signal (48.8-97.7 kHz, 3-6 seconds). All parameters auto-detected from metadata files.

📖 Full dataset documentation: data/README.md

Diagnose bearing fault in real_train/OuterRaceFault_1.csv
BPFO=81.13 Hz, BPFI=118.88 Hz, BSF=63.91 Hz, FTF=14.84 Hz

Result: ✅ Outer race fault detected at ~81 Hz with harmonics

Generate envelope report for real_train/OuterRaceFault_1.csv

Result: Interactive HTML saved to reports/ with bearing fault markers

Train anomaly model on baseline_1.csv and baseline_2.csv
Validate on OuterRaceFault_1.csv

Result: Model detects fault with 95%+ confidence

📚 More examples: EXAMPLES.md for complete diagnostic workflows

All analysis tools generate interactive HTML reports with Plotly visualizations:

✅ Universal - Works with any LLM (Claude, ChatGPT, local models)
✅ Zero tokens - Files saved locally, not in chat
✅ Interactive - Pan, zoom, hover for details
✅ Professional - Publication-ready visualizations
✅ Persistent - Save for documentation and sharing

All reports include:

• Interactive Plotly charts (pan/zoom/hover)
• Automatic peak detection with frequency tables
• Metadata (signal info, analysis parameters)
• Timestamp and file references

Usage:

Generate FFT report for baseline_1.csv

→ Opens reports/fft_spectrum_baseline_1_20251111_143022.html in browser

• EXAMPLES.md - Complete diagnostic workflows with step-by-step tutorials
• CONTRIBUTING.md - Contribution guidelines
• CHANGELOG.md - Version history

Use MCP Inspector for interactive testing:

npx @modelcontextprotocol/inspector npx predictive-maintenance-mcp

Or from source:

uv run mcp dev src/machinery_diagnostics_server.py

This project includes a comprehensive test suite covering all analysis tools:

# Run all tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_fft_analysis.py

# Run with verbose output
pytest -v

Test coverage includes:

• ✅ FFT analysis and peak detection
• ✅ Envelope analysis and bearing fault detection
• ✅ ISO 20816-3 evaluation and zone classification
• ✅ ML tools (feature extraction, training, prediction)
• ✅ Report generation system (HTML outputs)
• ✅ Real bearing fault data validation

See tests/README.md for detailed testing documentation.

pip install -e ".[dev]"

# Format code
black src/

# Type checking
mypy src/

# Linting
flake8 src/

AI-powered extraction of machine specifications from equipment manuals 🎉

The system now includes a hybrid documentation reader that combines:

• 📄 Direct PDF Access - MCP Resources for full manual text reading
• 🔍 Smart Extraction - Regex patterns for bearings, RPM, power ratings
• 🧮 Auto-Calculation - Bearing fault frequencies from geometry (ISO 15243:2017)
• 💾 Caching System - Fast repeated queries with JSON caching

What it can do:

"What bearings are used in this pump?"
→ Extracts: Drive end: SKF 6205-2RS, Non-drive end: NSK 6206

"Calculate bearing fault frequencies at 1475 RPM"
→ BPFO: 85.20 Hz, BPFI: 136.05 Hz, BSF: 101.32 Hz, FTF: 9.47 Hz

"What type of mechanical seal is used?"
→ Type 21, carbon/ceramic faces (extracted from manual text)

Status: ✅ Core functionality working, comprehensive tests passing

Known Limitations:

• PDF reading requires PyPDF2 (optional dependency)
• Limited bearing catalog (extensible)
• No OCR for scanned PDFs (planned for v0.4.0)

See resources/machine_manuals/README.md for usage guide.

For manuals >100 pages, semantic search will be more efficient:

• ChromaDB/FAISS integration - Embed PDF chunks for semantic search
• Query examples: "bearing specifications", "maintenance schedule", "lubrication requirements"
• Benefit: Faster than sequential reading, context-aware retrieval

Many older manuals are image-based PDFs:

• Tesseract integration - Extract text from scanned pages
• Preprocessing - Image enhancement for better accuracy
• Fallback: Graceful degradation if OCR unavailable

• Optional feature: Web search for unknown bearings
• Privacy-first: User must enable explicitly
• Sources: SKF/FAG public catalogs (no API required)

• Real-time streaming: Live vibration signal monitoring
• Multi-signal trending: Compare historical data across assets
• Dashboard: Multi-asset fleet monitoring interface
• Mobile reports: Responsive HTML reports for field use
• Cloud integration: Optional Azure/AWS storage for large datasets
• Multimodal fusion: Vibration + temperature + acoustic + oil analysis

💡 Have ideas? Open an issue or discussion to suggest features!

This project is licensed under the MIT License - see the LICENSE file for details.

Note: Sample data is licensed CC BY-NC-SA 4.0 (non-commercial). For commercial use, replace with your own machinery data.

If you use this server in your research or projects, please cite:

@software{dimaggio_predictive_maintenance_mcp_2025,
  title = {Predictive Maintenance MCP Server: An open-source framework for integrating Large Language Models with predictive maintenance and fault diagnosis workflows},
  author = {Di Maggio, Luigi Gianpio},
  year = {2025},
  version = {0.3.2},
  url = {https://github.com/LGDiMaggio/predictive-maintenance-mcp},
  doi = {10.5281/zenodo.17611542}
}

👉 Building an AI-Powered Predictive Maintenance System with MCP and Claude

• FastMCP framework by @jlowin
• Model Context Protocol by Anthropic
• Sample Data from MathWorks
• Development Assistance: Core codebase and demonstration examples were developed with assistance from Claude by Anthropic to rapidly prototype and demonstrate the Model Context Protocol (MCP) concept for predictive maintenance applications. The coding assistant tool enabled quick iteration on the architecture, testing framework, and CI/CD pipeline.

⚠️ Development Notice: This codebase was generated using Claude AI under human supervision to explore and validate MCP-based approaches for industrial diagnostics and predictive maintenance workflows. While the implementation demonstrates the potential of AI-assisted development for specialized engineering domains, thorough testing and validation are required before any production or safety-critical use. The project serves as a research prototype to evaluate how LLM-powered tools can enhance human expertise in machinery condition monitoring.

• Issues: https://github.com/LGDiMaggio/predictive-maintenance-mcp/issues
• Discussions: https://github.com/LGDiMaggio/predictive-maintenance-mcp/discussions

Built with ❤️ for condition monitoring professionals