mcp-server-mcsa 0.3.0

MCP server for Motor Current Signature Analysis (MCSA) — spectral analysis, fault frequency calculation, and fault detection in electric motors

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 -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: install with pip (not recommended — see note)

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.

Alternative: install from source (for development)

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.

License

MIT — see LICENSE for details.