JinDaGe - mcp-motor-current-signature-analysis MCP Details

article

README

🚀 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）

加载测量信号（或生成合成信号）：

"从 measurement.wav 文件加载信号" → 返回 signal_id: sig_a1b2 或者："生成一个带有断条故障的测试信号" → sig_c3d4
计算电机参数：

"计算一个 4 极、50 Hz 供电、转速 1470 RPM 的电机参数"
计算预期故障频率：

"该电机的预期故障频率是多少？"
预处理信号：

"预处理信号 sig_a1b2" → 返回新的 signal_id: sig_e5f6
分析频谱：

"计算 sig_e5f6 的 FFT 频谱" → 返回 spectrum_id: spec_g7h8
检测特定故障：

"检查 spec_g7h8 中是否存在断条故障"
包络分析（可选）：

"计算 sig_e5f6 的包络频谱"

从存储信号进行快速诊断

run_full_diagnosis 工具可以在一次调用中对存储的信号执行整个诊断流程：

输入：signal_id + 电机铭牌数据
输出：包含故障严重程度和建议的完整报告

轴承分析

进行轴承故障分析时，需要提供轴承的几何参数（滚珠数量、滚珠直径、节圆直径、接触角）。服务器将：

计算特征缺陷频率（BPFO、BPFI、BSF、FTF）
计算预期的电流边带
在频谱中搜索这些边带

支持的文件格式

| 格式 | 扩展名 | 采样率 | |------|--------|--------| | CSV / TSV | .csv, .tsv, .txt | 从时间列获取或用户提供 | | WAV | .wav | 嵌入在文件头中 | | NumPy | .npy | 用户提供 |

📚 详细文档

如需详细了解每个工具、资源和提示的参考信息，包括参数表、诊断工作流程、集成模式和严重程度阈值，请参阅 使用指南。

🔧 技术细节

断条故障（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 值）

| 级别 | 范围 | |------|------| | 健康 | ≤ −50 dB | | 初期 | −50 至 −45 dB | | 中度 | −45 至 −40 dB | | 严重 | > −35 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 会根据 CITATION.cff 文件自动显示 "引用此仓库" 按钮。

工具列表（共 21 个）

| 工具 | 描述 | |------|------| | inspect_signal_file | 检查信号文件格式和元数据，无需加载文件 | | load_signal_from_file | 从 CSV / WAV / NPY 文件加载电流信号 → 返回 signal_id | | calculate_motor_params | 根据电机数据计算转差率、同步速度和转子频率 | | compute_fault_frequencies | 计算所有常见故障类型的预期故障频率 | | compute_bearing_frequencies | 根据轴承几何形状计算 BPFO、BPFI、BSF、FTF | | preprocess_signal | 去除直流分量、滤波、归一化、加窗处理 → 返回新的 signal_id | | compute_spectrum | 计算单边 FFT 幅值频谱 → 返回 spectrum_id | | compute_power_spectral_density | 进行 Welch 功率谱密度估计 → 返回 spectrum_id | | find_spectrum_peaks | 检测并表征频谱中的峰值 | | detect_broken_rotor_bars | 检测断条故障并进行严重程度分类 | | detect_eccentricity | 通过边带检测气隙偏心故障 | | detect_stator_faults | 检测定子匝间短路故障 | | detect_bearing_faults | 从电流频谱中检测轴承缺陷 | | compute_envelope_spectrum | 计算希尔伯特包络频谱，用于调制分析 | | compute_band_energy | 计算频带内的积分频谱能量 | | compute_time_frequency | 进行 STFT 分析，可选择频率跟踪 | | generate_test_current_signal | 生成带有可选故障的合成电机电流 → 返回 signal_id | | run_full_diagnosis | 从信号或 signal_id 执行完整的 MCSA 诊断流程 | | diagnose_from_file | 直接从文件执行完整的 MCSA 诊断流程 | | list_stored_data | 列出磁盘上所有持久化的信号和频谱 | | clear_stored_data | 从磁盘删除一个或所有存储项 |

资源列表

| URI | 描述 | |-----|------| | mcsa://fault-signatures | 故障特征、频率和经验阈值的参考表 |

提示列表

| 提示 | 描述 | |------|------| | analyze_motor_current | MCSA 分析的分步指导工作流程 |

故障排除

| 问题 | 解决方法 | |------|------| | Claude Desktop 出现“服务器断开连接” | 检查日志文件：Windows 系统在 %APPDATA%\Claude\logs\，macOS 系统在 ~/Library/Logs/Claude/。最常见的原因是配置中的命令未找到。使用 uvx 可避免 PATH 问题。 | | 出现 uvx: command not found | 安装 uv 后重启终端。在 Windows 系统中，可能需要关闭并重新打开 PowerShell。 | | （使用 pip 安装时）出现 mcp-server-mcsa: command not found | 脚本未添加到 PATH 中。可使用 python -m mcp_server_mcsa 代替，或切换到 uvx。 | | 服务器启动但工具未显示 | 确保在编辑配置后重启了 MCP 客户端。 |

数据存储

信号和频谱以压缩的 .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 删除存储项。