MCP Motor Current Signature Analysis

🚀 mcp-server-mcsa

mcp-server-mcsa 是一個用於 電機電流特徵分析（Motor Current Signature Analysis，MCSA） 的 模型上下文協議（Model Context Protocol，MCP）服務器。它藉助定子電流信號，實現對電動機的非侵入式頻譜分析和故障檢測。通過集成 快速傅里葉變換（Fast Fourier Transform，FFT） 和 包絡分析 等先進技術，該系統能“聆聽”電機的電氣特徵，自動識別機械和電氣異常，並且可以通過自然語言交互。MCSA 是一種行業標準的狀態監測技術，可分析定子電流的諧波成分，檢測電動機的轉子、定子、軸承和氣隙故障，無需振動傳感器、停機或對機器進行物理訪問。此服務器將完整的 MCSA 診斷工作流程引入任何與 MCP 兼容的 AI 助手（如 Claude Desktop、VS Code Copilot 等），支持交互式專家分析和自動化狀態監測管道。

🚀 快速開始

步驟 1 — 安裝 uv（如果沒有安裝，只需執行一次）

uv 是推薦使用的 Python 包管理器。它能通過一個工具處理所有事務（Python、包、虛擬環境），並且在整個 MCP 生態系統中廣泛使用。

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

安裝完成後，請 重啟終端，以便 uv / uvx 命令可用。

步驟 2 — 驗證是否正常工作

uvx mcp-server-mcsa --help

你應該能看到幫助文本。就是這麼簡單 —— 無需使用 pip install。uvx 會在隔離環境中自動下載並運行該包。

步驟 3 — 添加到你的 MCP 客戶端

選擇你的客戶端，並添加以下配置。無需其他步驟。

Claude Desktop

打開配置文件：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

在 mcpServers 對象中添加 mcsa（如果文件不存在則創建）：

{
  "mcpServers": {
    "mcsa": {
      "command": "uvx",
      "args": ["mcp-server-mcsa"]
    }
  }
}

然後 重啟 Claude Desktop。

VS Code（Copilot / Continue）

在你的工作區創建（或編輯）.vscode/mcp.json 文件：

{
  "servers": {
    "mcsa": {
      "command": "uvx",
      "args": ["mcp-server-mcsa"]
    }
  }
}

Cursor

前往 設置 → MCP 服務器 → 添加新服務器：

• 類型：command
• 命令：uvx mcp-server-mcsa

步驟 4 — 測試

在你的 MCP 客戶端中，嘗試輸入：

"生成一個帶有斷條故障的測試信號並進行全面診斷。電機參數：4 極，50 Hz，1470 RPM。"

如果服務器返回診斷報告，則表示配置成功。

✨ 主要特性

• 真實信號加載 — 從 CSV、TSV、WAV 和 NumPy .npy 文件中讀取測量數據。
• 電機參數計算 — 根據銘牌數據計算轉差率、同步速度和轉子頻率。
• 故障頻率計算 — 計算斷條、偏心、定子故障、混合偏心等故障的頻率。
• 軸承缺陷頻率 — 根據軸承幾何形狀計算 BPFO、BPFI、BSF、FTF。
• 信號預處理 — 去除直流分量、歸一化、加窗、帶通/陷波濾波。
• 頻譜分析 — FFT 頻譜、Welch 功率譜密度估計、頻譜峰值檢測。
• 包絡分析 — 使用希爾伯特變換解調檢測機械/軸承故障。
• 時頻分析 — 採用 STFT 並進行頻率跟蹤，適用於非平穩條件。
• 故障檢測 — 自動進行嚴重程度分類（健康 / 初期 / 中度 / 嚴重）。
• 一次性診斷 — 從信號數組或直接從文件執行完整的診斷流程。
• 測試信號生成 — 生成可配置故障注入的合成信號，用於演示和基準測試。
• 持久數據存儲 — 信號和頻譜以壓縮的 .npz 文件形式保存到 ~/.mcsa_data/ 目錄中，通過短 ID（sig_xxxx，spec_xxxx）引用，避免大數組進入聊天上下文；數據在服務器重啟後仍然保留。

📦 安裝指南

替代方法：使用 pip 安裝（不推薦 — 詳見注意事項）

pip install mcp-server-mcsa

然後使用以下配置你的客戶端：

{
  "mcpServers": {
    "mcsa": {
      "command": "python",
      "args": ["-m", "mcp_server_mcsa"]
    }
  }
}

⚠️ Windows 常見問題：如果你從 Microsoft Store 安裝了 Python，mcp-server-mcsa 命令可能不在你的 PATH 中，導致出現“服務器斷開連接”錯誤。在這種情況下，使用 python -c "import sys; print(sys.executable)" 查找你的 Python 路徑，並在配置中使用完整路徑：

{
  "mcpServers": {
    "mcsa": {
      "command": "C:/Users/YOU/AppData/Local/.../python.exe",
      "args": ["-m", "mcp_server_mcsa"]
    }
  }
}

使用 uvx 可以完全避免此問題。

替代方法：從源代碼安裝（用於開發）

git clone https://github.com/LGDiMaggio/mcp-motor-current-signature-analysis.git
cd mcp-motor-current-signature-analysis
uv sync --dev

配置客戶端指向本地倉庫：

{
  "mcpServers": {
    "mcsa": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-motor-current-signature-analysis", "run", "mcp-server-mcsa"]
    }
  }
}

運行測試：

uv run pytest

使用 MCP Inspector 進行調試：

uv run mcp dev src/mcp_server_mcsa/server.py

💻 使用示例

真實信號 — 一次性診斷

分析測量信號的最快方法是使用 diagnose_from_file 工具。只需提供文件路徑和電機銘牌數據：

"對 C:\data\motor_phaseA.csv 文件中的電機進行診斷 — 供電頻率 50 Hz，4 極，轉速 1470 RPM"

服務器將加載文件、預處理信號、計算頻譜、運行所有故障檢測器，並返回一個包含嚴重程度分類結果的完整 JSON 報告。

分步工作流程（使用信號 ID）

1. 加載測量信號（或生成合成信號）：

   "從 measurement.wav 文件加載信號" → 返回 signal_id: sig_a1b2 或者："生成一個帶有斷條故障的測試信號" → sig_c3d4

2. 計算電機參數：

   "計算一個 4 極、50 Hz 供電、轉速 1470 RPM 的電機參數"

3. 計算預期故障頻率：

   "該電機的預期故障頻率是多少？"

4. 預處理信號：

   "預處理信號 sig_a1b2" → 返回新的 signal_id: sig_e5f6

5. 分析頻譜：

   "計算 sig_e5f6 的 FFT 頻譜" → 返回 spectrum_id: spec_g7h8

6. 檢測特定故障：

   "檢查 spec_g7h8 中是否存在斷條故障"

7. 包絡分析（可選）：

   "計算 sig_e5f6 的包絡頻譜"

從存儲信號進行快速診斷

run_full_diagnosis 工具可以在一次調用中對存儲的信號執行整個診斷流程：

輸入：signal_id + 電機銘牌數據
輸出：包含故障嚴重程度和建議的完整報告

軸承分析

進行軸承故障分析時，需要提供軸承的幾何參數（滾珠數量、滾珠直徑、節圓直徑、接觸角）。服務器將：

1. 計算特徵缺陷頻率（BPFO、BPFI、BSF、FTF）
2. 計算預期的電流邊帶
3. 在頻譜中搜索這些邊帶

支持的文件格式

📚 詳細文檔

如需詳細瞭解每個工具、資源和提示的參考信息，包括參數表、診斷工作流程、集成模式和嚴重程度閾值，請參閱 使用指南。

🔧 技術細節

斷條故障（BRB）

在 $(1 \pm 2s) \cdot f_s$ 處出現邊帶，其中 $s$ 是轉差率，$f_s$ 是供電頻率。嚴重程度通過邊帶與基波幅值的 dB 比值進行分類。

偏心故障

在 $f_s \pm k \cdot f_r$ 處出現邊帶，其中 $f_r$ 是轉子機械頻率。

定子匝間故障

由於繞組不對稱，在 $f_s \pm 2k \cdot f_r$ 處出現邊帶。

軸承缺陷

轉矩振盪會調製定子電流，在 $f_s \pm k \cdot f_{defect}$ 處產生邊帶。缺陷頻率取決於軸承幾何形狀（BPFO、BPFI、BSF、FTF）。

嚴重程度閾值（相對於基波的 dB 值）

注意：這些是一般指導原則。實際閾值應根據基線測量結果，針對特定電機、負載和應用進行調整。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

開發相關

環境搭建

git clone https://github.com/LGDiMaggio/mcp-motor-current-signature-analysis.git
cd mcp-motor-current-signature-analysis
uv sync --dev

運行測試

uv run pytest

使用 MCP Inspector 運行

uv run mcp dev src/mcp_server_mcsa/server.py

代碼檢查和類型檢查

uv run ruff check src/ tests/
uv run pyright src/

依賴項

• mcp — 模型上下文協議 SDK
• numpy — 數值計算庫
• scipy — 信號處理庫（FFT、濾波、希爾伯特變換）
• pydantic — 數據驗證庫

引用

如果您在研究中使用了此軟件，請引用：

@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 會根據 文件自動顯示 "引用此倉庫" 按鈕。

工具列表（共 21 個）

資源列表

提示列表

故障排除

數據存儲

信號和頻譜以壓縮的 .npz 文件形式 持久化到磁盤，存儲在 ~/.mcsa_data/ 目錄中（可通過 MCSA_DATA_DIR 環境變量進行配置）。這意味著：

• 大數組不會進入聊天 — 僅將短 ID（sig_xxxx，spec_xxxx）和簡潔摘要返回給大語言模型。
• 數據在服務器重啟後仍然保留 — 明天重新打開 Claude Desktop，你的信號仍然可用。
• 所有數據集中存儲 — 加載的測量數據和生成的測試信號都存儲在同一文件夾中。

~/.mcsa_data/
  signals/
    sig_a1b2c3d4.npz   ← 從 CSV 文件加載
    sig_e5f6g7h8.npz   ← 生成的測試信號
  spectra/
    spec_i9j0k1l2.npz  ← FFT 結果

使用 list_stored_data 查看磁盤上的所有數據，使用 clear_stored_data 刪除存儲項。