Motor Current Signature Analysis

mcp-server-mcsa

<!-- mcp-name: io.github.LGDiMaggio/mcp-server-mcsa -->

  

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

mcp-server-mcsa turns any LLM into a predictive-maintenance expert. By integrating advanced techniques such as Fast Fourier Transform (FFT) and envelope analysis, the system can listen to a motor's electrical signature and automatically identify mechanical and electrical anomalies — all through natural language.

MCSA is an industry-standard condition-monitoring technique that analyses the harmonic content of the stator current to detect rotor, stator, bearing, and air-gap faults in electric motors — without requiring vibration sensors, downtime, or physical access to the machine. This server brings the full MCSA diagnostic workflow to any MCP-compatible AI assistant (Claude Desktop, VS Code Copilot, and others), enabling both interactive expert analysis and automated condition-monitoring pipelines.

Features

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

Tools (21)

| Tool | Description | |------|-------------| | inspect_signal_file | Inspect a signal file format and metadata without loading | | load_signal_from_file | Load a current signal from CSV / WAV / NPY file → returns signal_id | | calculate_motor_params | Compute slip, sync speed, rotor frequency from motor data | | compute_fault_frequencies | Calculate expected fault frequencies for all common fault types | | compute_bearing_frequencies | Calculate BPFO, BPFI, BSF, FTF from bearing geometry | | preprocess_signal | DC removal, filtering, normalisation, windowing pipeline → returns new signal_id | | compute_spectrum | Single-sided FFT amplitude spectrum → returns spectrum_id | | compute_power_spectral_density | Welch PSD estimation → returns spectrum_id | | find_spectrum_peaks | Detect and characterise peaks in a spectrum | | detect_broken_rotor_bars | BRB fault index with severity classification | | detect_eccentricity | Air-gap eccentricity detection via sidebands | | detect_stator_faults | Stator inter-turn short circuit detection | | detect_bearing_faults | Bearing defect detection from current spectrum | | compute_envelope_spectrum | Hilbert envelope spectrum for modulation analysis | | compute_band_energy | Integrated spectral energy in a frequency band | | compute_time_frequency | STFT analysis with optional frequency tracking | | generate_test_current_signal | Synthetic motor current with optional faults → returns signal_id | | run_full_diagnosis | Complete MCSA diagnostic pipeline from signal or signal_id | | diagnose_from_file | Complete MCSA diagnostic pipeline directly from file | | list_stored_data | List all signals and spectra persisted on disk | | clear_stored_data | Delete one or all stored items from disk |

Resources

| URI | Description | |-----|-------------| | mcsa://fault-signatures | Reference table of fault signatures, frequencies, and empirical thresholds |

Prompts

| Prompt | Description | |--------|-------------| | analyze_motor_current | Step-by-step guided workflow for MCSA analysis |

Installation & Setup

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 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``

macOS / Linux: ``bash 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.

---

<details> <summary><strong>Alternative: install with pip</strong> (not recommended — see note)</summary>

pip install mcp-server-mcsa

Then configure your client with:

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

⚠️ Common issue on Windows: if you installed Python from the Microsoft Store, the mcp-server-mcsa command may not be in your PATH, causing a "server disconnected" error. In that case, find your Python path with python -c "import sys; print(sys.executable)" and use the full path in the config: ``json { "mcpServers": { "mcsa": { "command": "C:/Users/YOU/AppData/Local/.../python.exe", "args": ["-m", "mcp_server_mcsa"] } } } ` Using uvx` avoids this problem entirely.

</details>

<details> <summary><strong>Alternative: install from source</strong> (for development)</summary>

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

Configure the client to point to the local repo:

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

Run tests:

uv run pytest

Debug with MCP Inspector:

uv run mcp dev src/mcp_server_mcsa/server.py

</details>

Troubleshooting

| Problem | Fix | |---------|-----| | "server disconnected" on Claude Desktop | Check the logs at %APPDATA%\Claude\logs\ (Windows) or ~/Library/Logs/Claude/ (macOS). Most common cause: the command in the config is not found. Use uvx to avoid PATH issues. | | uvx: command not found | Restart your terminal after installing uv. On Windows, you may need to close and reopen PowerShell. | | mcp-server-mcsa: command not found (pip) | The script wasn't added to PATH. Use python -m mcp_server_mcsa instead, or switch to uvx. | | Server starts but tools don't appear | Make sure you restarted the MCP client after editing the config. |

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.

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

1. Calculate motor parameters:

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

1. Compute expected fault frequencies:

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

1. Preprocess the signal:

"Preprocess signal sig_a1b2" → returns new signal_id: sig_e5f6

1. Analyse the spectrum:

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

1. Detect specific faults:

"Check for broken rotor bars in spec_g7h8"

1. 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

| Format | Extensions | Sampling Rate | |--------|------------|---------------| | CSV / TSV | .csv, .tsv, .txt | From time column or user-supplied | | WAV | .wav | Embedded in header | | NumPy | .npy | User-supplied |

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)

| Level | Range | |-------|-------| | Healthy | ≤ −50 dB | | Incipient | −50 to −45 dB | | Moderate | −45 to −40 dB | | Severe | > −35 dB |

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

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

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.

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 CITATION.cff file.


License

MIT — see LICENSE for details.