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"]
    }
  }
}
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

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

MCP Motor Current Signature Analysis

Install / Use

README