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)

Resources

Prompts

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.

<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

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

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.

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](USAGE_GUIDE.md).

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.