{
"markdown": "# mcp-server-mcsa\n\n\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://modelcontextprotocol.io)\n\nA **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.\n\n> **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.\n\nMCSA 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.\n\n## Features\n\n- **Real signal loading** — read measured data from CSV, TSV, WAV, and NumPy `.npy` files\n- **Motor parameter calculation** — slip, synchronous speed, rotor frequency from nameplate data\n- **Fault frequency computation** — broken rotor bars, eccentricity, stator faults, mixed eccentricity\n- **Bearing defect frequencies** — BPFO, BPFI, BSF, FTF from bearing geometry\n- **Signal preprocessing** — DC removal, normalisation, windowing, bandpass/notch filtering\n- **Spectral analysis** — FFT spectrum, Welch PSD, spectral peak detection\n- **Envelope analysis** — Hilbert-transform demodulation for mechanical/bearing faults\n- **Time-frequency analysis** — STFT with frequency tracking for non-stationary conditions\n- **Fault detection** — automated severity classification (healthy / incipient / moderate / severe)\n- **One-shot diagnostics** — full pipeline from signal array or directly from file\n- **Test signal generation** — synthetic signals with configurable fault injection for demos and benchmarking\n- **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\n\n## Tools (21)\n\n| Tool | Description |\n|------|-------------|\n| `inspect_signal_file` | Inspect a signal file format and metadata without loading |\n| `load_signal_from_file` | Load a current signal from CSV / WAV / NPY file → returns `signal_id` |\n| `calculate_motor_params` | Compute slip, sync speed, rotor frequency from motor data |\n| `compute_fault_frequencies` | Calculate expected fault frequencies for all common fault types |\n| `compute_bearing_frequencies` | Calculate BPFO, BPFI, BSF, FTF from bearing geometry |\n| `preprocess_signal` | DC removal, filtering, normalisation, windowing pipeline → returns new `signal_id` |\n| `compute_spectrum` | Single-sided FFT amplitude spectrum → returns `spectrum_id` |\n| `compute_power_spectral_density` | Welch PSD estimation → returns `spectrum_id` |\n| `find_spectrum_peaks` | Detect and characterise peaks in a spectrum |\n| `detect_broken_rotor_bars` | BRB fault index with severity classification |\n| `detect_eccentricity` | Air-gap eccentricity detection via sidebands |\n| `detect_stator_faults` | Stator inter-turn short circuit detection |\n| `detect_bearing_faults` | Bearing defect detection from current spectrum |\n| `compute_envelope_spectrum` | Hilbert envelope spectrum for modulation analysis |\n| `compute_band_energy` | Integrated spectral energy in a frequency band |\n| `compute_time_frequency` | STFT analysis with optional frequency tracking |\n| `generate_test_current_signal` | Synthetic motor current with optional faults → returns `signal_id` |\n| `run_full_diagnosis` | Complete MCSA diagnostic pipeline from signal or `signal_id` |\n| `diagnose_from_file` | Complete MCSA diagnostic pipeline directly from file |\n| `list_stored_data` | List all signals and spectra persisted on disk |\n| `clear_stored_data` | Delete one or all stored items from disk |\n\n## Resources\n\n| URI | Description |\n|-----|-------------|\n| `mcsa://fault-signatures` | Reference table of fault signatures, frequencies, and empirical thresholds |\n\n## Prompts\n\n| Prompt | Description |\n|--------|-------------|\n| `analyze_motor_current` | Step-by-step guided workflow for MCSA analysis |\n\n## Installation & Setup\n\n### Step 1 — Install uv (one-time, if you don't have it)\n\n[uv](https://docs.astral.sh/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.\n\n**Windows** (PowerShell):\n```powershell\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\n**macOS / Linux**:\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n> After installing, **restart your terminal** so the `uv` / `uvx` commands are available.\n\n### Step 2 — Verify it works\n\n```bash\nuvx mcp-server-mcsa --help\n```\n\nYou should see the help text. **That's it** — no `pip install` needed. `uvx` downloads and runs the package automatically in an isolated environment.\n\n### Step 3 — Add to your MCP client\n\nPick your client and add the configuration below. **No other steps are required.**\n\n#### Claude Desktop\n\nOpen the config file:\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\nAdd `mcsa` inside the `mcpServers` object (create the file if it doesn't exist):\n\n```json\n{\n \"mcpServers\": {\n \"mcsa\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-server-mcsa\"]\n }\n }\n}\n```\n\nThen **restart Claude Desktop**.\n\n#### VS Code (Copilot / Continue)\n\nCreate (or edit) `.vscode/mcp.json` in your workspace:\n\n```json\n{\n \"servers\": {\n \"mcsa\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-server-mcsa\"]\n }\n }\n}\n```\n\n#### Cursor\n\nGo to **Settings → MCP Servers → Add new server**:\n- Type: `command`\n- Command: `uvx mcp-server-mcsa`\n\n### Step 4 — Test\n\nIn your MCP client, try:\n\n> \"Generate a test signal with a broken rotor bar fault and run a full diagnosis. Motor: 4 poles, 50 Hz, 1470 RPM.\"\n\nIf the server responds with a diagnostic report, you're all set.\n\n---\n\n\nAlternative: install with pip (not recommended — see note)
\n\n```bash\npip install mcp-server-mcsa\n```\n\nThen configure your client with:\n\n```json\n{\n \"mcpServers\": {\n \"mcsa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp_server_mcsa\"]\n }\n }\n}\n```\n\n> **⚠️ 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:\n>\n> ```json\n> {\n> \"mcpServers\": {\n> \"mcsa\": {\n> \"command\": \"C:/Users/YOU/AppData/Local/.../python.exe\",\n> \"args\": [\"-m\", \"mcp_server_mcsa\"]\n> }\n> }\n> }\n> ```\n>\n> Using `uvx` avoids this problem entirely.\n\n \n\n\nAlternative: install from source (for development)
\n\n```bash\ngit clone https://github.com/LGDiMaggio/mcp-motor-current-signature-analysis.git\ncd mcp-motor-current-signature-analysis\nuv sync --dev\n```\n\nConfigure the client to point to the local repo:\n\n```json\n{\n \"mcpServers\": {\n \"mcsa\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"/absolute/path/to/mcp-motor-current-signature-analysis\", \"run\", \"mcp-server-mcsa\"]\n }\n }\n}\n```\n\nRun tests:\n\n```bash\nuv run pytest\n```\n\nDebug with MCP Inspector:\n\n```bash\nuv run mcp dev src/mcp_server_mcsa/server.py\n```\n\n \n\n### Troubleshooting\n\n| Problem | Fix |\n|---------|-----|\n| \"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. |\n| `uvx: command not found` | Restart your terminal after installing uv. On Windows, you may need to close and reopen PowerShell. |\n| `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`. |\n| Server starts but tools don't appear | Make sure you restarted the MCP client after editing the config. |\n\n## Data Store\n\nSignals and spectra are **persisted to disk** as compressed `.npz` files\nin `~/.mcsa_data/` (configurable via the `MCSA_DATA_DIR` environment\nvariable). This means:\n\n- **Large arrays never enter the chat** — only short IDs (`sig_xxxx`,\n `spec_xxxx`) and compact summaries are returned to the LLM.\n- **Data survives server restarts** — reopen Claude Desktop tomorrow and\n your signals are still there.\n- **All data in one place** — loaded measurements and generated test\n signals live side by side in the same folder.\n\n```\n~/.mcsa_data/\n signals/\n sig_a1b2c3d4.npz ← loaded from CSV\n sig_e5f6g7h8.npz ← generated test signal\n spectra/\n spec_i9j0k1l2.npz ← FFT result\n```\n\nUse `list_stored_data` to see everything on disk and `clear_stored_data`\nto remove items.\n\n## Usage Examples\n\n### Real Signal — One-Shot Diagnosis\n\nThe fastest way to analyse a measured signal is the `diagnose_from_file`\ntool. Simply provide the file path and motor nameplate data:\n\n> \"Diagnose the motor from `C:\\data\\motor_phaseA.csv` — 50 Hz supply,\n> 4 poles, 1470 RPM\"\n\nThe server loads the file, preprocesses the signal, computes the spectrum,\nruns all fault detectors, and returns a complete JSON report with\nseverity-classified results.\n\n### Step-by-Step Workflow (with signal IDs)\n\n1. **Load a measured signal** (or generate a synthetic one):\n > \"Load the signal from `measurement.wav`\" → returns `signal_id: sig_a1b2`\n > or: \"Generate a test signal with a broken-rotor-bar fault\" → `sig_c3d4`\n\n2. **Calculate motor parameters**:\n > \"Calculate motor parameters for a 4-pole motor, 50 Hz supply, running at 1470 RPM\"\n\n3. **Compute expected fault frequencies**:\n > \"What are the expected fault frequencies for this motor?\"\n\n4. **Preprocess the signal**:\n > \"Preprocess signal sig_a1b2\" → returns new `signal_id: sig_e5f6`\n\n5. **Analyse the spectrum**:\n > \"Compute the FFT spectrum of sig_e5f6\" → returns `spectrum_id: spec_g7h8`\n\n6. **Detect specific faults**:\n > \"Check for broken rotor bars in spec_g7h8\"\n\n7. **Envelope analysis (optional)**:\n > \"Compute the envelope spectrum of sig_e5f6\"\n\n### Quick Diagnosis from Stored Signal\n\nThe `run_full_diagnosis` tool runs the entire pipeline on a stored signal\nin a single call:\n\n```\nInput: signal_id + motor nameplate data\nOutput: complete report with fault severities and recommendations\n```\n\n### Bearing Analysis\n\nFor bearing fault analysis, you need the bearing geometry (number of balls,\nball diameter, pitch diameter, contact angle). The server will:\n1. Calculate characteristic defect frequencies (BPFO, BPFI, BSF, FTF)\n2. Compute expected current sidebands\n3. Search the spectrum for those sidebands\n\n### Supported File Formats\n\n| Format | Extensions | Sampling Rate |\n|--------|------------|---------------|\n| CSV / TSV | `.csv`, `.tsv`, `.txt` | From time column or user-supplied |\n| WAV | `.wav` | Embedded in header |\n| NumPy | `.npy` | User-supplied |\n\n## Fault Detection Theory\n\n### Broken Rotor Bars (BRB)\nSidebands at $(1 \\pm 2s) \\cdot f_s$ where $s$ is slip and $f_s$ is supply frequency.\nSeverity is classified by the dB ratio of sideband to fundamental amplitude.\n\n### Eccentricity\nSidebands at $f_s \\pm k \\cdot f_r$ where $f_r$ is the rotor mechanical frequency.\n\n### Stator Inter-Turn Faults\nSidebands at $f_s \\pm 2k \\cdot f_r$ due to winding asymmetry.\n\n### Bearing Defects\nTorque oscillations modulate the stator current, creating sidebands at $f_s \\pm k \\cdot f_{defect}$.\nDefect frequencies depend on bearing geometry (BPFO, BPFI, BSF, FTF).\n\n### Severity Thresholds (dB below fundamental)\n\n| Level | Range |\n|-------|-------|\n| Healthy | ≤ −50 dB |\n| Incipient | −50 to −45 dB |\n| Moderate | −45 to −40 dB |\n| Severe | > −35 dB |\n\n> **Note**: These are general guidelines. Actual thresholds should be adapted to the specific motor, load, and application based on baseline measurements.\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/LGDiMaggio/mcp-motor-current-signature-analysis.git\ncd mcp-motor-current-signature-analysis\nuv sync --dev\n```\n\n### Run tests\n\n```bash\nuv run pytest\n```\n\n### Run with MCP Inspector\n\n```bash\nuv run mcp dev src/mcp_server_mcsa/server.py\n```\n\n### Lint and type check\n\n```bash\nuv run ruff check src/ tests/\nuv run pyright src/\n```\n\n## Dependencies\n\n- [mcp](https://pypi.org/project/mcp/) — Model Context Protocol SDK\n- [numpy](https://numpy.org/) — numerical computing\n- [scipy](https://scipy.org/) — signal processing (FFT, filtering, Hilbert transform)\n- [pydantic](https://docs.pydantic.dev/) — data validation\n\n## Documentation\n\nFor a detailed reference of every tool, resource, and prompt — including\nparameter tables, diagnostic workflows, integration patterns, and severity\nthresholds — see the **[Usage Guide](USAGE_GUIDE.md)**.\n\n## Citation\n\nIf you use this software in your research, please cite it:\n\n```bibtex\n@software{dimaggio_mcsa_2025,\n author = {Di Maggio, Luigi Gianpio},\n title = {mcp-server-mcsa: MCP Server for Motor Current Signature Analysis},\n year = 2025,\n url = {https://github.com/LGDiMaggio/mcp-motor-current-signature-analysis},\n license = {MIT}\n}\n```\n\n> GitHub shows a **\"Cite this repository\"** button automatically from the [`CITATION.cff`](CITATION.cff) file.\n\n[](https://orcid.org/0000-0002-2295-8944)\n\n## License\n\nMIT — see [LICENSE](LICENSE) for details.\n",
"bytes": 14282,
"sha": "f1932af9a8ea3073d0bba1c1b4a99e3201aa59104a5522bb96fec47a1c12d84f",
"repo_slug": "lgdimaggio/mcp-motor-current-signature-analysis",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_lgdimaggio_mcp_server_mcsa_47e49a0c/readme"
}