MCP Motor Current Signature Analysis

🚀 mcp-server-mcsa

A Model Context Protocol (MCP) server for Motor Current Signature Analysis (MCSA) — enabling non-invasive spectral analysis and fault detection in electric motors using stator-current signals.

🚀 Quick Start

The mcp-server-mcsa is a powerful tool that transforms any LLM into a predictive-maintenance expert. By integrating advanced techniques like Fast Fourier Transform (FFT) and envelope analysis, it can "listen" to a motor's electrical signature and automatically identify mechanical and electrical anomalies through natural language.

✨ Features

• Real signal loading: Read measured data from CSV, TSV, WAV, and NumPy .npy files.
• Motor parameter calculation: Compute slip, synchronous speed, and rotor frequency from nameplate data.
• Fault frequency computation: Calculate expected fault frequencies for broken rotor bars, eccentricity, stator faults, and mixed eccentricity.
• Bearing defect frequencies: Determine BPFO, BPFI, BSF, FTF from bearing geometry.
• Signal preprocessing: Perform DC removal, normalisation, windowing, and bandpass/notch filtering.
• Spectral analysis: Conduct FFT spectrum, Welch PSD, and spectral peak detection.
• Envelope analysis: Use Hilbert-transform demodulation for mechanical/bearing faults.
• Time-frequency analysis: Apply STFT with frequency tracking for non-stationary conditions.
• Fault detection: Automate severity classification (healthy / incipient / moderate / severe).
• One-shot diagnostics: Run the full pipeline from a signal array or directly from a file.
• Test signal generation: Create synthetic signals with configurable fault injection for demos and benchmarking.
• Persistent data store: Save signals and spectra as compressed .npz files in ~/.mcsa_data/, referenced by short IDs (sig_xxxx, spec_xxxx), and the data survives server restarts.

📦 Installation

Step 1 — Install uv (one-time, if you don't have it)

uv is the recommended Python package manager. It handles everything (Python, packages, virtual environments) in a single tool and is used throughout the MCP ecosystem.

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

After installing, restart your terminal so the uv / uvx commands are available.

Step 2 — Verify it works

uvx mcp-server-mcsa --help

You should see the help text. That's it — no pip install needed. uvx downloads and runs the package automatically in an isolated environment.

Step 3 — Add to your MCP client

Pick your client and add the configuration below. No other steps are required.

Claude Desktop

Open the config file:

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

Add mcsa inside the mcpServers object (create the file if it doesn't exist):

{
  "mcpServers": {
    "mcsa": {
      "command": "uvx",
      "args": ["mcp-server-mcsa"]
    }
  }
}

Then restart Claude Desktop.

VS Code (Copilot / Continue)

Create (or edit) .vscode/mcp.json in your workspace:

{
  "servers": {
    "mcsa": {
      "command": "uvx",
      "args": ["mcp-server-mcsa"]
    }
  }
}

Cursor

Go to Settings → MCP Servers → Add new server:

• Type: command
• Command: uvx mcp-server-mcsa

Step 4 — Test

In your MCP client, try:

"Generate a test signal with a broken rotor bar fault and run a full diagnosis. Motor: 4 poles, 50 Hz, 1470 RPM."

If the server responds with a diagnostic report, you're all set.

Alternative Installation Methods

pip install mcp-server-mcsa

{
  "mcpServers": {
    "mcsa": {
      "command": "python",
      "args": ["-m", "mcp_server_mcsa"]
    }
  }
}

git clone https://github.com/LGDiMaggio/mcp-motor-current-signature-analysis.git
cd mcp-motor-current-signature-analysis
uv sync --dev

{
  "mcpServers": {
    "mcsa": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-motor-current-signature-analysis", "run", "mcp-server-mcsa"]
    }
  }
}

uv run pytest

uv run mcp dev src/mcp_server_mcsa/server.py

Troubleshooting

💻 Usage Examples

Real Signal — One-Shot Diagnosis

The fastest way to analyse a measured signal is the diagnose_from_file tool. Simply provide the file path and motor nameplate data:

"Diagnose the motor from C:\data\motor_phaseA.csv — 50 Hz supply, 4 poles, 1470 RPM"

The server loads the file, preprocesses the signal, computes the spectrum, runs all fault detectors, and returns a complete JSON report with severity-classified results.

Step-by-Step Workflow (with signal IDs)

1. Load a measured signal (or generate a synthetic one):

   "Load the signal from measurement.wav" → returns signal_id: sig_a1b2 or: "Generate a test signal with a broken-rotor-bar fault" → sig_c3d4

2. Calculate motor parameters:

   "Calculate motor parameters for a 4-pole motor, 50 Hz supply, running at 1470 RPM"

3. Compute expected fault frequencies:

   "What are the expected fault frequencies for this motor?"

4. Preprocess the signal:

   "Preprocess signal sig_a1b2" → returns new signal_id: sig_e5f6

5. Analyse the spectrum:

   "Compute the FFT spectrum of sig_e5f6" → returns spectrum_id: spec_g7h8

6. Detect specific faults:

   "Check for broken rotor bars in spec_g7h8"

7. Envelope analysis (optional):

   "Compute the envelope spectrum of sig_e5f6"

Quick Diagnosis from Stored Signal

The run_full_diagnosis tool runs the entire pipeline on a stored signal in a single call:

Input: signal_id + motor nameplate data
Output: complete report with fault severities and recommendations

Bearing Analysis

For bearing fault analysis, you need the bearing geometry (number of balls, ball diameter, pitch diameter, contact angle). The server will:

1. Calculate characteristic defect frequencies (BPFO, BPFI, BSF, FTF)
2. Compute expected current sidebands
3. Search the spectrum for those sidebands

Supported File Formats

🔧 Technical Details

Fault Detection Theory

Broken Rotor Bars (BRB)

Sidebands at $(1 \pm 2s) \cdot f_s$ where $s$ is slip and $f_s$ is supply frequency. Severity is classified by the dB ratio of sideband to fundamental amplitude.

Eccentricity

Sidebands at $f_s \pm k \cdot f_r$ where $f_r$ is the rotor mechanical frequency.

Stator Inter-Turn Faults

Sidebands at $f_s \pm 2k \cdot f_r$ due to winding asymmetry.

Bearing Defects

Torque oscillations modulate the stator current, creating sidebands at $f_s \pm k \cdot f_{defect}$. Defect frequencies depend on bearing geometry (BPFO, BPFI, BSF, FTF).

Severity Thresholds (dB below fundamental)

Note: These are general guidelines. Actual thresholds should be adapted to the specific motor, load, and application based on baseline measurements.

📚 Documentation

For a detailed reference of every tool, resource, and prompt — including parameter tables, diagnostic workflows, integration patterns, and severity thresholds — see the Usage Guide.

📄 License

This project is licensed under the MIT License. See LICENSE for details.

📦 Tools (21)

📋 Resources

📝 Prompts

🛠️ Development

Setup

git clone https://github.com/LGDiMaggio/mcp-motor-current-signature-analysis.git
cd mcp-motor-current-signature-analysis
uv sync --dev

Run tests

uv run pytest

Run with MCP Inspector

uv run mcp dev src/mcp_server_mcsa/server.py

Lint and type check

uv run ruff check src/ tests/
uv run pyright src/

📌 Dependencies

• mcp — Model Context Protocol SDK
• numpy — numerical computing
• scipy — signal processing (FFT, filtering, Hilbert transform)
• pydantic — data validation

📜 Citation

If you use this software in your research, please cite it:

@software{dimaggio_mcsa_2025,
  author       = {Di Maggio, Luigi Gianpio},
  title        = {mcp-server-mcsa: MCP Server for Motor Current Signature Analysis},
  year         = 2025,
  url          = {https://github.com/LGDiMaggio/mcp-motor-current-signature-analysis},
  license      = {MIT}
}

GitHub shows a "Cite this repository" button automatically from the file.

💾 Data Store

Signals and spectra are persisted to disk as compressed .npz files in ~/.mcsa_data/ (configurable via the MCSA_DATA_DIR environment variable). This means:

• Large arrays never enter the chat — only short IDs (sig_xxxx, spec_xxxx) and compact summaries are returned to the LLM.
• Data survives server restarts — reopen Claude Desktop tomorrow and your signals are still there.
• All data in one place — loaded measurements and generated test signals live side by side in the same folder.

~/.mcsa_data/
  signals/
    sig_a1b2c3d4.npz   ← loaded from CSV
    sig_e5f6g7h8.npz   ← generated test signal
  spectra/
    spec_i9j0k1l2.npz  ← FFT result

Use list_stored_data to see everything on disk and clear_stored_data to remove items.