Skip to main content
Glama
mcp-server-mcsa

mcp-server-mcsa

mcp-server-mcsa

License: MIT Python 3.10+ MCP

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

Related MCP server: motor-telemetry-mcp

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


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:

{
  "mcpServers": {
    "mcsa": {
      "command": "C:/Users/YOU/AppData/Local/.../python.exe",
      "args": ["-m", "mcp_server_mcsa"]
    }
  }
}

Using uvx avoids this problem entirely.

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

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

  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

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.

ORCID

License

MIT — see LICENSE for details.

Available Tools

21 tools
calculate_motor_paramsA

Calculate motor operating parameters from nameplate and measured data.

Computes synchronous speed, slip, rotor frequency, and slip frequency. These parameters are required inputs for fault frequency calculations.

Inputs: supply_freq_hz (required), poles (required), rotor_speed_rpm (required). Returns: result

clear_stored_dataA

Delete stored signals and spectra from disk and memory.

Pass a specific data_id to remove one item, or omit to clear all.

Inputs: data_id. Returns: result

compute_band_energyB

Compute the integrated spectral energy in a frequency band.

Useful as a generic fault/cavitation indicator — measures the energy concentration around a characteristic frequency in the PSD.

Inputs: centre_freq_hz (required), spectrum_id, frequencies_hz, psd_values, +1 more. Returns: result

compute_bearing_frequenciesA

Calculate bearing characteristic defect frequencies (BPFO, BPFI, BSF, FTF).

Returns normalised frequencies (multiples of shaft speed) and, if shaft speed is provided, absolute frequencies in Hz. If supply frequency is also given, computes expected stator-current sidebands.

Inputs: n_balls (required), ball_dia_mm (required), pitch_dia_mm (required), contact_angle_deg, +2 more. Returns: result

compute_envelope_spectrumA

Compute the envelope spectrum of a current signal.

Uses the Hilbert transform to extract the amplitude envelope, then computes its FFT. Useful for detecting bearing and mechanical faults that modulate the current at low frequencies.

Inputs: signal_id, signal, sampling_freq_hz, bandpass_low_hz, +2 more. Returns: result

compute_fault_frequenciesA

Calculate expected fault frequencies for common induction-motor faults.

Computes characteristic frequencies for broken rotor bars, eccentricity, stator faults, and mixed eccentricity based on motor operating parameters. Use these frequencies to know WHERE to look in the current spectrum.

Inputs: supply_freq_hz (required), poles (required), rotor_speed_rpm (required), harmonics. Returns: result

compute_power_spectral_densityB

Compute Power Spectral Density using Welch's method.

Better for noisy signals and trend analysis than a raw FFT. Returns a spectrum_id plus compact summary.

Inputs: signal_id, signal, sampling_freq_hz, nperseg, +1 more. Returns: result

compute_spectrumA

Compute the single-sided amplitude spectrum (FFT) of a current signal.

Returns a spectrum_id referencing the stored spectrum, plus a compact summary with top peaks. Use spectrum_id in downstream fault-detection tools.

Inputs: signal_id, signal, sampling_freq_hz, n_fft, +1 more. Returns: result

compute_time_frequencyA

Compute Short-Time Fourier Transform (STFT) for time-frequency analysis.

For non-stationary conditions (variable speed/load, start-up transients). If target_freq_hz is provided, also tracks that frequency's amplitude over time. Returns a summary (not the full 2D matrix) to keep output manageable.

Inputs: signal_id, signal, sampling_freq_hz, nperseg, +2 more. Returns: result

detect_bearing_faultsA

Detect bearing defect signatures in the stator-current spectrum.

Bearing faults modulate motor torque, creating sidebands at f_s ± k·f_defect. Note: bearing signatures in current are typically weak; envelope analysis or vibration data can improve detection.

Inputs: spectrum_id, frequencies_hz, amplitudes, supply_freq_hz, +4 more. Returns: result

detect_broken_rotor_barsA

Detect broken rotor bar faults from current spectrum.

Computes the BRB fault index by measuring sidebands at (1 ± 2s)·f_s relative to the fundamental. Returns severity classification: healthy / incipient / moderate / severe.

Inputs: spectrum_id, frequencies_hz, amplitudes, supply_freq_hz, +3 more. Returns: result

detect_eccentricityA

Detect air-gap eccentricity faults from current spectrum.

Analyses sidebands at f_s ± k·f_r for static and dynamic eccentricity. Returns severity classification.

Inputs: spectrum_id, frequencies_hz, amplitudes, supply_freq_hz, +4 more. Returns: result

detect_stator_faultsB

Detect stator inter-turn short circuit faults from current spectrum.

Analyses sidebands at f_s ± 2k·f_r caused by stator winding asymmetry.

Inputs: spectrum_id, frequencies_hz, amplitudes, supply_freq_hz, +4 more. Returns: result

diagnose_from_fileA

Load a signal from file and run the full MCSA diagnostic pipeline.

One-shot tool: reads the signal file, preprocesses, computes the spectrum, runs all fault detectors, and returns a complete diagnostic report. Ideal for batch or automated condition-monitoring workflows.

Inputs: file_path (required), supply_freq_hz (required), poles (required), rotor_speed_rpm (required), +6 more. Returns: result

find_spectrum_peaksA

Detect peaks in a frequency spectrum.

Returns a list of peaks sorted by amplitude (highest first) with frequency, amplitude, and prominence values.

Inputs: spectrum_id, frequencies_hz, amplitudes, min_height, +5 more. Returns: result

generate_test_current_signalA

Generate a synthetic motor-current test signal.

Creates a simulated stator-current waveform with the fundamental, supply harmonics, noise, and optional fault signatures. Useful for testing, validation, and demonstration of MCSA analysis tools.

Inputs: duration_s, sampling_freq_hz, supply_freq_hz, poles, +4 more. Returns: result

inspect_signal_fileA

Inspect a signal file without fully loading it.

Returns file metadata: size, format details, estimated number of samples, sampling frequency (for WAV), column headers (for CSV), and array shape (for NPY). Use this before load_signal_from_file to verify the file format and plan the loading parameters.

Inputs: file_path (required). Returns: result

list_stored_dataA

List all signals and spectra currently stored on disk.

Returns a compact summary of each stored item (ID, type, size, and key metadata) without returning the raw data arrays. The data is persisted in the MCSA data directory and survives server restarts.

Inputs: no named parameters. Returns: result

load_signal_from_fileA

Load a motor-current signal from a file (CSV, WAV, or NumPy NPY).

Supports the most common formats used by industrial DAQ systems:

  • CSV/TSV/TXT: Columnar data with optional time column. The sampling frequency is inferred from the time column or must be provided explicitly.

  • WAV: Audio files from portable recorders or DAQ. Sampling frequency is read from the WAV header.

  • NPY: NumPy binary arrays. Sampling frequency must be provided.

Returns the signal, sampling frequency, number of samples, duration, and file metadata. The returned signal can then be passed to preprocess_signal, compute_spectrum, or run_full_diagnosis.

Inputs: file_path (required), sampling_freq_hz, signal_column, time_column, +4 more. Returns: result

preprocess_signalA

Preprocess a stator-current signal for spectral analysis.

Applies (in order): DC offset removal → notch filtering → bandpass filtering → normalisation → windowing. Returns the preprocessed signal.

Inputs: signal (required), sampling_freq_hz (required), nominal_current, window, +3 more. Returns: result

run_full_diagnosisA

Run a comprehensive MCSA diagnostic analysis on a current signal.

Performs the full pipeline: preprocessing → spectrum → fault detection for broken rotor bars, eccentricity, stator faults, and optionally bearing defects. Returns a complete diagnostic report.

Inputs: signal_id, signal, sampling_freq_hz, supply_freq_hz, +4 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 21 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose. Spectrum-related tools are differentiated by method (FFT, Welch, envelope, STFT). Fault detection tools are separated by fault type (bearing, rotor bar, eccentricity, stator). Workflow tools like run_full_diagnosis and diagnose_from_file are distinct in input method. No ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., compute_spectrum, detect_broken_rotor_bars). The verbs are descriptive and uniform, making the set predictable and easy to navigate.

    Tool Count4/5

    With 21 tools, the set is slightly above the typical 3-15 range but still reasonable given the comprehensive domain coverage. Each tool serves a specific, necessary function in the MCSA pipeline, so the count feels appropriate rather than bloated.

    Completeness5/5

    The tool set covers the entire MCSA workflow: file inspection, loading, preprocessing, multiple spectrum computation methods, fault-specific detection, and automated full-diagnosis pipelines. Utilities for data management (list/clear stored data) and test signal generation are included, leaving no obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes industrial motor telemetry data to AI agents via MCP and REST, enabling natural-language queries about motor status, health, and alerts. Provides a single tool and resource for retrieving real-time motor metrics and escalating critical conditions.
      MIT