mcp-server-mcsa
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-mcsa Analyze motor current from signal.wav"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
.npyfilesMotor 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.npzfiles; 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 a signal file format and metadata without loading |
| Load a current signal from CSV / WAV / NPY file → returns |
| Compute slip, sync speed, rotor frequency from motor data |
| Calculate expected fault frequencies for all common fault types |
| Calculate BPFO, BPFI, BSF, FTF from bearing geometry |
| DC removal, filtering, normalisation, windowing pipeline → returns new |
| Single-sided FFT amplitude spectrum → returns |
| Welch PSD estimation → returns |
| Detect and characterise peaks in a spectrum |
| BRB fault index with severity classification |
| Air-gap eccentricity detection via sidebands |
| Stator inter-turn short circuit detection |
| Bearing defect detection from current spectrum |
| Hilbert envelope spectrum for modulation analysis |
| Integrated spectral energy in a frequency band |
| STFT analysis with optional frequency tracking |
| Synthetic motor current with optional faults → returns |
| Complete MCSA diagnostic pipeline from signal or |
| Complete MCSA diagnostic pipeline directly from file |
| List all signals and spectra persisted on disk |
| Delete one or all stored items from disk |
Resources
URI | Description |
| Reference table of fault signatures, frequencies, and empirical thresholds |
Prompts
Prompt | Description |
| 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 | shAfter installing, restart your terminal so the
uv/uvxcommands are available.
Step 2 — Verify it works
uvx mcp-server-mcsa --helpYou 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.jsonmacOS:
~/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:
commandCommand:
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-mcsaThen 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-mcsacommand may not be in your PATH, causing a "server disconnected" error. In that case, find your Python path withpython -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
uvxavoids this problem entirely.
git clone https://github.com/LGDiMaggio/mcp-motor-current-signature-analysis.git
cd mcp-motor-current-signature-analysis
uv sync --devConfigure 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 pytestDebug with MCP Inspector:
uv run mcp dev src/mcp_server_mcsa/server.pyTroubleshooting
Problem | Fix |
"server disconnected" on Claude Desktop | Check the logs at |
| Restart your terminal after installing uv. On Windows, you may need to close and reopen PowerShell. |
| The script wasn't added to PATH. Use |
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 resultUse 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)
Load a measured signal (or generate a synthetic one):
"Load the signal from
measurement.wav" → returnssignal_id: sig_a1b2or: "Generate a test signal with a broken-rotor-bar fault" →sig_c3d4Calculate motor parameters:
"Calculate motor parameters for a 4-pole motor, 50 Hz supply, running at 1470 RPM"
Compute expected fault frequencies:
"What are the expected fault frequencies for this motor?"
Preprocess the signal:
"Preprocess signal sig_a1b2" → returns new
signal_id: sig_e5f6Analyse the spectrum:
"Compute the FFT spectrum of sig_e5f6" → returns
spectrum_id: spec_g7h8Detect specific faults:
"Check for broken rotor bars in spec_g7h8"
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 recommendationsBearing Analysis
For bearing fault analysis, you need the bearing geometry (number of balls, ball diameter, pitch diameter, contact angle). The server will:
Calculate characteristic defect frequencies (BPFO, BPFI, BSF, FTF)
Compute expected current sidebands
Search the spectrum for those sidebands
Supported File Formats
Format | Extensions | Sampling Rate |
CSV / TSV |
| From time column or user-supplied |
WAV |
| Embedded in header |
NumPy |
| 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 --devRun tests
uv run pytestRun with MCP Inspector
uv run mcp dev src/mcp_server_mcsa/server.pyLint 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.cfffile.
License
MIT — see LICENSE for details.
Available Tools
21 toolscalculate_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
Scored across 21 tools
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.
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.
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.
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
Related MCP Connectors
Predictive maintenance failure risk assessment, delivered per API call on Conduit Atoms.
AI-powered diagnostics for elevator, escalator, and vertical transportation equipment
Electrical machinery engineering check, delivered per API call as an atom service on Conduit Atoms.
13 neural engines for time-series anomaly detection, classification, and root cause analysis.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI assistants to analyze vibration data, detect machinery faults, and generate professional diagnostic reports through natural conversation.3469 PyPI114MIT
- AlicenseNot gradedqualityCmaintenanceExposes 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
- AlicenseNot gradedqualityDmaintenanceEnables exploration of manufacturing equipment data and analysis of failure risk, supporting monitoring, failure classification, and anomaly detection through natural language.MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to load vibration signals, detect machinery faults with spectral evidence, assess severity against ISO 20816-3, and generate diagnostic reports locally without guessing.38MIT