{"id":44175980,"url":"https://github.com/lgdimaggio/predictive-maintenance-mcp","last_synced_at":"2026-04-02T18:03:42.742Z","repository":{"id":324246838,"uuid":"1094130680","full_name":"LGDiMaggio/predictive-maintenance-mcp","owner":"LGDiMaggio","description":"AI-Powered Predictive Maintenance \u0026 Fault Diagnosis through Model Context Protocol. An open-source framework for integrating Large Language Models with predictive maintenance and fault diagnosis workflows.","archived":false,"fork":false,"pushed_at":"2026-02-09T13:21:05.000Z","size":68712,"stargazers_count":15,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-09T16:38:49.108Z","etag":null,"topics":["anomaly-detection","asset-management","bearing-fault-diagnosis","claude-agents","claude-ai","condition-monitoring","envelope-analysis","fastmcp","fault-diagnosis","iiot","industrial-iot","industry-4-0","iso10816","machine-failure","mcp-server","model-context-protocol","predictive-analytics","predictive-maintenance","signal-processing","vibration-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LGDiMaggio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":".zenodo.json","notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-11T09:49:39.000Z","updated_at":"2026-02-09T13:21:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/LGDiMaggio/predictive-maintenance-mcp","commit_stats":null,"previous_names":["lgdimaggio/predictive-maintenance-mcp"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/LGDiMaggio/predictive-maintenance-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGDiMaggio%2Fpredictive-maintenance-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGDiMaggio%2Fpredictive-maintenance-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGDiMaggio%2Fpredictive-maintenance-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGDiMaggio%2Fpredictive-maintenance-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LGDiMaggio","download_url":"https://codeload.github.com/LGDiMaggio/predictive-maintenance-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGDiMaggio%2Fpredictive-maintenance-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29477308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T11:35:25.641Z","status":"ssl_error","status_checked_at":"2026-02-15T11:34:57.128Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anomaly-detection","asset-management","bearing-fault-diagnosis","claude-agents","claude-ai","condition-monitoring","envelope-analysis","fastmcp","fault-diagnosis","iiot","industrial-iot","industry-4-0","iso10816","machine-failure","mcp-server","model-context-protocol","predictive-analytics","predictive-maintenance","signal-processing","vibration-analysis"],"created_at":"2026-02-09T13:08:09.985Z","updated_at":"2026-04-02T18:03:42.691Z","avatar_url":"https://github.com/LGDiMaggio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Predictive Maintenance MCP Server\n\n\u003c!-- mcp-name: io.github.LGDiMaggio/predictive-maintenance-mcp --\u003e\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17611542.svg)](https://doi.org/10.5281/zenodo.17611542)\n[![Tests](https://github.com/LGDiMaggio/predictive-maintenance-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/LGDiMaggio/predictive-maintenance-mcp/actions/workflows/tests.yml)\n[![codecov](https://codecov.io/gh/LGDiMaggio/predictive-maintenance-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/LGDiMaggio/predictive-maintenance-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Give any AI assistant the ability to analyze vibration data, detect machinery faults, and generate professional diagnostic reports — through natural conversation.**\n\nAn open-source [MCP](https://modelcontextprotocol.io/) server and **Claude Code plugin** 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. It's designed to **support and accelerate expert decision-making**, not replace it — the engineer stays in control.\n\n---\n\n## Quick Start\n\n```bash\npip install predictive-maintenance-mcp\n```\n\nAdd to your Claude Desktop config (`%APPDATA%\\Claude\\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"predictive-maintenance\": {\n      \"command\": \"predictive-maintenance-mcp\"\n    }\n  }\n}\n```\n\nRestart Claude Desktop. You're ready — try: *\"Load real_train/OuterRaceFault_1.csv and check if the bearing is healthy.\"*\n\n\u003e **More options**: [install from source](INSTALL.md) · [VS Code setup](INSTALL.md) · [Docker / HTTPS deployment](docs/DEPLOYMENT.md) · [use with local LLMs (Ollama)](docs/OLLAMA_GUIDE.md)\n\n---\n\n## What Can It Do?\n\n**Upload a vibration signal → get a professional diagnosis through conversation.**\n\n| You say | The AI does |\n|---------|-------------|\n| *\"Is this bearing healthy?\"* | Loads the signal, runs spectral analysis, checks for fault patterns, classifies severity |\n| *\"Generate a full diagnostic report\"* | Produces an interactive HTML report with charts, fault markers, and severity assessment |\n| *\"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 |\n| *\"Train an anomaly detector on my healthy baselines, then flag anomalies\"* | Trains a machine learning model on normal data, scores new signals, highlights outliers |\n\nThe 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.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSee the full endpoint list (52 MCP endpoints: 43 tools, 1 resource, 4 prompts)\u003c/b\u003e\u003c/summary\u003e\n\n### Signal Acquisition (7 tools + 2 resources)\n\n| Endpoint | Type | Description |\n|----------|------|-------------|\n| `load_signal` | Tool | Load vibration file (CSV, WAV, MAT, NPY, Parquet) |\n| `list_signals` | Tool | Browse available signal files with metadata |\n| `list_stored_signals` | Tool | List cached signals in memory |\n| `get_signal_info` | Tool | Signal metadata (sampling rate, duration, stats) |\n| `generate_test_signal` | Tool | Create synthetic signals for testing |\n| `clear_signal` / `clear_all_signals` | Tool | Cache management |\n| `signal://list` | Resource | Browse all signal files |\n| `signal://read/{filename}` | Resource | Read signal metadata |\n\n### Spectral \u0026 Statistical Analysis (10 tools)\n\n| Tool | Description |\n|------|-------------|\n| `analyze_fft` | Frequency spectrum with automatic peak detection |\n| `analyze_envelope` | Envelope analysis for bearing fault detection |\n| `analyze_statistics` | Time-domain features (RMS, kurtosis, crest factor) |\n| `compute_power_spectral_density` | Power spectral density (Welch method) |\n| `compute_spectrogram_stft` | Time-frequency spectrogram |\n| `extract_features_from_signal` | 17+ statistical and spectral features |\n| `compute_envelope_spectrum_tool` | Envelope spectrum computation |\n| `plot_signal` / `plot_spectrum` / `plot_envelope` | Visualization tools (3 tools) |\n\n### Diagnostics \u0026 Health Assessment (14 tools)\n\n| Tool | Description |\n|------|-------------|\n| `calculate_bearing_characteristic_frequencies` | Compute expected fault frequencies from bearing geometry |\n| `check_bearing_fault_peak_tool` | Detect peaks at fault frequencies |\n| `check_bearing_faults_direct` | Multi-fault detection (inner/outer/ball/cage) |\n| `diagnose_vibration_tool` | Integrated evidence-based diagnosis pipeline |\n| `search_bearing_catalog` | Look up bearing specs by model number |\n| `lookup_bearing_and_compute_tool` | Catalog lookup + frequency calculation |\n| `evaluate_iso_20816` | Vibration severity assessment (4 severity zones) |\n| `assess_vibration_severity` | Health classification |\n| `train_anomaly_model` | Train novelty detection on healthy baselines |\n| `predict_anomalies` | Score new signals for anomalies |\n| `search_documentation` | Semantic search over equipment manuals |\n| `read_manual_excerpt` / `extract_manual_specs` | Extract specs from PDFs (2 tools) |\n| `list_machine_manuals` | Browse available documentation |\n\n### Reporting (9 tools)\n\n| Tool | Description |\n|------|-------------|\n| `generate_fft_report` | Interactive frequency analysis report |\n| `generate_envelope_report` | Envelope analysis with fault markers |\n| `generate_iso_report` | Severity zone visualization |\n| `generate_diagnostic_report_docx` | Structured Word document report |\n| `generate_pca_visualization_report` | 2D/3D anomaly projection |\n| `generate_feature_comparison_report` | Cross-signal feature comparison |\n| `plot_iso_20816_chart` | ISO 20816 severity zone chart |\n| `list_html_reports` / `get_report_info` | Report management (2 tools) |\n\n### Prognostics (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `estimate_rul` | Remaining Useful Life estimation (linear, exponential, Weibull, Kalman) |\n| `analyze_signal_trend` | Trend detection on feature time series (increasing/decreasing/stable) |\n| `detect_signal_degradation_onset` | Baseline deviation detection for early degradation warning |\n\n### Decision Support (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `check_vibration_alert` | ISO 10816 vibration severity alert classification (zones A/B/C/D) |\n| `check_custom_vibration_alert` | Custom threshold-based vibration alerting |\n| `generate_maintenance_recommendations` | Context-aware maintenance recommendations from diagnosis |\n\n### Guided Workflows (4 prompts + 2 resources)\n\n| Prompt | Description |\n|--------|-------------|\n| `diagnose_bearing` | Complete bearing fault diagnostic decision tree |\n| `diagnose_gear` | Gear fault detection workflow |\n| `quick_diagnostic_report` | Fast health screening |\n| `generate_iso_diagnostic_report` | ISO-compliant diagnostic report generation |\n\n\u003c/details\u003e\n\n---\n\n## Claude Code Plugin\n\nThe 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.\n\n```shell\n/plugin marketplace add LGDiMaggio/predictive-maintenance-mcp\n/plugin install predictive-maintenance@predictive-maintenance-marketplace\n```\n\n### Skills (7) — activate automatically based on context\n\n| Skill | What it does |\n|-------|-------------|\n| **bearing-diagnosis** | Walks through a complete bearing fault diagnostic workflow |\n| **gear-diagnosis** | Gear fault detection via spectral pattern analysis |\n| **quick-screening** | 30-second vibration health check |\n| **report-generation** | Professional HTML and Word report generation |\n| **anomaly-detection** | Train and run ML-based anomaly detection models |\n| **signal-management** | Load, inspect, and manage vibration signals |\n| **documentation-search** | Search equipment manuals and bearing catalogs |\n\n### Agents (2) — run autonomously for complex tasks\n\n| Agent | What it does |\n|-------|-------------|\n| **diagnostic-pipeline** | End-to-end: load signal → spectral analysis → fault detection → severity assessment → report |\n| **signal-explorer** | Explore and compare multiple signals, find outliers, characterize patterns |\n\n### Commands (3) — quick entry points\n\n| Command | Example |\n|---------|---------|\n| `/pm-diagnose` | `/pm-diagnose bearing_signal.csv` — full fault diagnosis |\n| `/pm-screen` | `/pm-screen bearing_signal.csv` — quick health check |\n| `/pm-report` | `/pm-report bearing_signal.csv full` — generate all reports |\n\n---\n\n## Reports\n\nAll analysis tools generate **interactive HTML reports** you can open in any browser — pan, zoom, hover for details. Also supports structured Word (.docx) exports.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eReport examples\u003c/b\u003e\u003c/summary\u003e\n\n![Envelope Analysis Report](assets/envelope_analysis.png)\n\n![ISO Severity Assessment](assets/iso.png)\n\n| Report Type | What it shows |\n|-------------|---------------|\n| Frequency spectrum | Peak detection, harmonic markers |\n| Envelope analysis | Bearing fault frequency matching |\n| Severity assessment | Vibration health zones (ISO 20816-3) |\n| Word document | Full diagnostic narrative with embedded charts |\n| PCA visualization | Multi-signal anomaly clustering |\n| Feature comparison | Side-by-side signal feature analysis |\n\n\u003c/details\u003e\n\n---\n\n## Sample Data Included\n\nThe project ships with **20 real bearing vibration signals** from production machinery tests — ready to use out of the box.\n\n- **Training set**: 2 healthy baselines + 12 fault signals (inner race, outer race)\n- **Test set**: 1 healthy baseline + 5 fault signals\n\nTry: *\"Load real_train/OuterRaceFault_1.csv and diagnose the bearing fault.\"*\n\nFull dataset documentation: [data/README.md](data/README.md)\n\n---\n\n## Architecture\n\n```\n          YOU (natural language)\n               │\n               v\n     LLM (Claude, GPT, Ollama...)\n     understands intent, selects tools\n               │\n               v  ── Model Context Protocol ──\n    ┌──────────────────────────────┐\n    │    Predictive Maintenance    │\n    │         MCP Server           │\n    │                              │\n    │  Signal Analysis    Reports  │\n    │  Fault Detection    ML       │\n    │  Severity Rating    RAG Docs │\n    └──────────────────────────────┘\n               │\n               v\n       YOUR DATA (stays local)\n    signals · manuals · models\n```\n\nThe 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.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDetailed module structure\u003c/b\u003e\u003c/summary\u003e\n\n```\nsrc/predictive_maintenance_mcp/\n├── mcp_tools/                 # MCP endpoint registration (52 MCP endpoints)\n│   ├── acquisition_tools.py   # Signal loading \u0026 management\n│   ├── analysis_tools.py      # Spectral \u0026 statistical analysis\n│   ├── diagnostics_tools.py   # Fault detection, ML, document search\n│   ├── report_tools.py        # HTML/DOCX report generation\n│   ├── prompts.py             # Guided diagnostic workflows\n│   └── _utils.py              # Shared utilities\n├── signal_acquisition/        # Multi-format loaders (CSV, MAT, WAV, NPY, Parquet)\n├── signal_processing/         # Spectral analysis \u0026 feature extraction\n├── diagnostics/               # Bearing/gear analysis, ISO standards\n├── decision_support/          # Evidence-based diagnosis pipeline\n├── prognostics/               # RUL estimation (linear, exponential, Weibull) \u0026 trend analysis\n├── rag.py                     # Document indexing \u0026 search (FAISS/TF-IDF)\n├── models.py                  # Pydantic data models\n├── server.py                  # FastMCP server entry point\n└── config.py                  # Configuration management\n```\n\n**Standards implemented**: ISO 13374 (diagnostic architecture), ISO 20816-3 (vibration severity classification), MIMOSA OSA-CBM (condition-based maintenance framework).\n\n\u003c/details\u003e\n\n**Key design choices:**\n- **Privacy-first** — raw vibration data never leaves your machine; only computed results flow to the LLM\n- **LLM-agnostic** — works with Claude, ChatGPT, Microsoft Copilot Studio, or any MCP-compatible client. Use [Ollama](docs/OLLAMA_GUIDE.md) for fully air-gapped deployments\n- **Modular** — use only the tools you need, extend with your own\n\n---\n\n## Documentation\n\n| Guide | For |\n|-------|-----|\n| [Quickstart for Engineers](docs/QUICKSTART_ENGINEER.md) | Get results fast, no coding required |\n| [Quickstart for Developers](docs/QUICKSTART_DEVELOPER.md) | Understand MCP, extend the server |\n| [Plugin README](plugin/README.md) | Claude Code plugin installation and usage |\n| [HTTPS Deployment](docs/DEPLOYMENT.md) | Docker + HTTPS for enterprise environments |\n| [Ollama Guide](docs/OLLAMA_GUIDE.md) | Use with local LLMs (fully air-gapped) |\n| [Architecture](docs/architecture.md) | ISO 13374 block mapping and module design |\n| [Examples](EXAMPLES.md) | Complete diagnostic workflows |\n| [Installation](INSTALL.md) | Detailed setup and troubleshooting |\n| [Contributing](CONTRIBUTING.md) | How to contribute (all skill levels welcome) |\n| [Changelog](CHANGELOG.md) | Version history |\n\n---\n\n## Testing\n\n**86% test coverage** across Windows, macOS, and Linux (Python 3.11 \u0026 3.12).\n\n```bash\npytest                                  # run all tests\npytest --cov=src --cov-report=html      # with coverage report\n```\n\n20+ test files covering signal analysis, fault detection, severity assessment, ML models, report generation, RAG search, and real bearing fault data validation.\n\n---\n\n## Roadmap\n\n- [x] 52 MCP endpoints (43 tools, 1 resource, 4 prompts) with modular architecture\n- [x] Claude Code plugin (7 skills, 2 agents, 3 commands)\n- [x] 86% test coverage, CI/CD on 3 platforms\n- [x] Docker + SSE/HTTP transport for enterprise deployment\n- [x] Semantic document search (FAISS + TF-IDF)\n- [ ] Customizable severity thresholds\n- [x] Remaining useful life (RUL) estimation models (linear, exponential, Weibull degradation)\n- [x] Trend analysis and degradation onset detection\n- [ ] Multi-signal trending and historical comparison\n- [ ] Real-time streaming (MQTT/Kafka)\n- [ ] Fleet dashboard for multi-asset monitoring\n- [ ] CMMS integration (SAP, Maximo, Infor)\n\n\u003e Ideas? [Open a discussion](https://github.com/LGDiMaggio/predictive-maintenance-mcp/discussions) or [create an issue](https://github.com/LGDiMaggio/predictive-maintenance-mcp/issues/new/choose).\n\n---\n\n## Related\n\n**[claude-stwinbox-diagnostics](https://github.com/LGDiMaggio/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.\n\n---\n\n## Contributing\n\nContributions welcome from **everyone** — not just programmers. Domain experts, technical writers, and testers are equally valued. See [CONTRIBUTING.md](CONTRIBUTING.md) for paths tailored to your background.\n\n**Quick start**: browse [Issues](https://github.com/LGDiMaggio/predictive-maintenance-mcp/issues) for `good first issue` or `help wanted` labels.\n\n---\n\n## Citation\n\n```bibtex\n@software{dimaggio_predictive_maintenance_mcp_2025,\n  title   = {Predictive Maintenance MCP Server},\n  author  = {Di Maggio, Luigi Gianpio},\n  year    = {2025},\n  version = {0.8.0},\n  url     = {https://github.com/LGDiMaggio/predictive-maintenance-mcp},\n  doi     = {10.5281/zenodo.17611542}\n}\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE). Sample data is CC BY-NC-SA 4.0 (non-commercial); for commercial use, replace with your own machinery data.\n\n## Acknowledgments\n\n[FastMCP](https://github.com/jlowin/fastmcp) framework · [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic · Sample data from [MathWorks](https://github.com/mathworks/RollingElementBearingFaultDiagnosis-Data) · Core development assisted by [Claude](https://claude.ai)\n\n---\n\n*An open-source AI assistant for predictive maintenance — built to support reliability engineers and the developer community.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flgdimaggio%2Fpredictive-maintenance-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flgdimaggio%2Fpredictive-maintenance-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flgdimaggio%2Fpredictive-maintenance-mcp/lists"}