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

> {

>   "mcpServers": {

>     "mcsa": {

>       "command": "C:/Users/YOU/AppData/Local/.../python.exe",

>       "args": ["-m", "mcp_server_mcsa"]

>     }

>   }

> }

> 

</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:

…