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 删除存储项。