# EIS ECM DRT MCP

English | 中文

This project is an MCP server for batch EIS analysis. It reads EIS files or folders and outputs ECM fitting parameters, DRT curves, reconstructed impedance data, summaries, and optional plots.

The project keeps a two-layer structure:

• eis_ecm_drt/: core algorithms, including column detection, ECM fitting, DRT inversion, plotting, and batch output.

• eis_ecm_drt/mcp_server.py: a thin MCP interface layer that validates user selections and calls the core algorithms.

If you need to fix or improve the algorithm later, edit the core code under eis_ecm_drt/, then restart the MCP server.

Features

• Batch processing for .xlsx, .xls, .csv, .tsv, and .txt files.

• Automatic detection of frequency, real impedance, and imaginary impedance columns.

• Automatic imaginary-sign normalization. Output uses the -Zimag convention while also preserving the physical imaginary impedance column.

• Four primary ECM models, plus custom equivalent-circuit expressions.

• DRT parameters must be explicitly selected or approved by the user.

• Outputs ECM parameters, DRT curves, fitting data, summary CSV files, and optional PNG plots.

• Default output folder is a new subfolder under desktop EIS Analysis output, so the input data folder stays clean.

Related MCP server: spicelib-mcp

From GitHub To Installation

Clone the repository:

git clone <your GitHub repository URL>
cd <project folder>

If you already have the source code locally, enter the project root directly, for example:

cd C:\Users\wzd\Documents\电池软件

Python 3.10 or newer is recommended:

py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e ".[mcp]"

You can also use the bundled one-click script. On first run, it creates .venv and installs dependencies:

.\run_mcp.cmd

Command-line analysis example:

.\eis-analysis.cmd "test_cases/demo_eis/demo_eis.csv" --ecm-model L-R0-RQ-W --no-plots

Start MCP

After installation, start the MCP server with:

.\.venv\Scripts\eis-ecm-drt-mcp.exe

Or start it as a Python module:

.\.venv\Scripts\python.exe -m eis_ecm_drt.mcp_server

Example MCP client configuration:

{
  "mcpServers": {
    "eis-ecm-drt": {
      "command": "C:\\path\\to\\EIS-Analysis-mcp\\run_mcp.cmd",
      "args": []
    }
  }
}

Reusable config examples are also provided:

• examples/mcp_config_windows.json

• examples/mcp_config_macos_linux.json

After configuring the client, refresh or restart the MCP connection. If eis-ecm-drt appears as an available MCP server, the connection is ready.

How To Use After MCP Is Connected

Once connected, you do not need to manually run command-line scripts. Ask your MCP client to call the tools exposed by this project.

Recommended workflow:

1. Call list_ecm_models and let the user choose one or more ECM models.

2. Call list_drt_options and let the user choose or approve DRT parameters.

3. If the input format is uncertain, call validate_eis or validate_eis_batch first.

4. For one file, call analyze_eis_file.

5. For batch processing, call analyze_eis_batch.

6. Open README_输出说明.txt and batch_summary.csv in the output folder.

By default, final results are written to the desktop:

D:\desktop\EIS Analysis output\batch_YYYYMMDD_HHMMSS\

Each analysis creates a new subfolder under EIS Analysis output. The MCP response also includes output_dir, readme_path, and summary_path.

Example user request:

Use eis-ecm-drt to analyze D:\desktop\EIS验证\温度估计_基础电池_txt.
I choose ECM model L-R0-RQ-W.
Use the recommended DRT configuration.
Batch process all files, automatically detect frequency, real, and imaginary columns, write final results to the desktop EIS Analysis output folder, and generate plots.

To compare multiple ECM models:

Batch analyze D:\desktop\EIS验证\温度估计_基础电池_txt.
Fit and compare L-R0-RQ, L-R0-2RQ, L-R0-RQ-W, and L-R0-2RQ-W.
Use the recommended DRT configuration.
Write final results to the desktop EIS Analysis output folder.

Important: before formal analysis, the ECM model and DRT parameters must be explicit. The MCP server will not silently choose them for the user.

MCP Tools

• list_ecm_models: list the four primary ECM models and custom-expression format.

• list_drt_options: list required DRT fields and the recommended configuration.

• validate_eis: validate one file or one in-memory EIS dataset.

• validate_eis_batch: validate multiple files, folders, or glob patterns.

• fit_ecm: fit one selected ECM model to one in-memory dataset.

• calculate_drt: calculate DRT using a user-selected DRT configuration.

• analyze_eis_file: analyze one EIS file.

• analyze_eis_batch: batch analyze files, folders, or glob patterns.

For analyze_eis_file and analyze_eis_batch, the caller must pass:

• ecm_models: one or more ECM model IDs or custom expressions.

• drt_config: a full DRT configuration dictionary.

• ecm_models_confirmed_by_user: true.

• drt_config_confirmed_by_user: true.

If these fields are missing, the MCP tool raises an error.

ECM Model Choices

Notes:

• L1: high-frequency inductance.

• R0: ohmic resistance.

• R1/R2: polarization or charge-transfer resistance.

• CPE1/CPE2: constant phase elements, output as CPE*_Q and CPE*_n.

• W1: Warburg diffusion impedance with one parameter in this implementation.

• ||: parallel connection.

• -: series separator in the code expression, equivalent to + in circuit notation.

Custom expressions are also supported, for example:

L1-R0-(R1||CPE1)-(R2-W1||CPE2)

DRT Parameter Choices

Call list_drt_options first and let the user confirm the DRT configuration. The recommended commercial-aligned configuration is:

{
  "lambda_value": 0.01,
  "n_tau": 750,
  "regularization_order": 1,
  "basis_function": "gaussian",
  "shape_factor": 0.72,
  "n_basis": 220,
  "polarization_removal": "ignore_polarization",
  "boundary_suppression_factor": 0.10,
  "nonnegative": true,
  "fit_r_inf": true,
  "fit_inductance": true,
  "weighting": "modulus"
}

Parameter notes:

• lambda_value: regularization strength.

• n_tau: number of DRT output points.

• regularization_order: derivative regularization order. Commercial setting is first order.

• basis_function: recommended value is gaussian.

• shape_factor: Gaussian basis width. The current 0.72 is calibrated against the provided commercial DRT curves.

• n_basis: internal number of Gaussian coefficients. Recommended value is 220; output still has n_tau=750 points.

• polarization_removal: recommended value is ignore_polarization.

• boundary_suppression_factor: boundary suppression strength. Recommended value is 0.10.

• fit_inductance: whether to fit high-frequency inductance.

• weighting: recommended value is modulus.

Batch Analysis Example

Example MCP call for analyze_eis_batch:

{
  "inputs": ["D:/desktop/EIS验证/温度估计_基础电池_txt"],
  "recursive": false,
  "ecm_models": ["L-R0-RQ-W"],
  "ecm_models_confirmed_by_user": true,
  "drt_config": {
    "lambda_value": 0.01,
    "n_tau": 750,
    "regularization_order": 1,
    "basis_function": "gaussian",
    "shape_factor": 0.72,
    "n_basis": 220,
    "polarization_removal": "ignore_polarization",
    "boundary_suppression_factor": 0.10,
    "nonnegative": true,
    "fit_r_inf": true,
    "fit_inductance": true,
    "weighting": "modulus"
  },
  "drt_config_confirmed_by_user": true,
  "make_plots": true,
  "continue_on_error": true
}

If output_dir is not provided, results are written to:

D:\desktop\EIS Analysis output\batch_YYYYMMDD_HHMMSS\

Input Data Rules

Recommended data columns:

Headerless files are also supported. The program detects the frequency column using numeric features such as positive values, wide logarithmic range, and approximate monotonic ordering. After finding the frequency column, it prefers the next two adjacent columns as real and imaginary impedance.

Imaginary sign is normalized to the -Zimag convention:

• If the low-frequency imaginary values are positive, the source data is treated as already using -Zimag.

• If the low-frequency imaginary values are negative, the source data is treated as physical Zimag and is multiplied by -1 for output display.

Internal calculations still use physical complex impedance: Z = Zreal + j Zimag.

Output Files

Each sample may output:

• README_输出说明.txt: output folder guide. Open this first.

• *_ecm_params.csv: ECM parameters.

• *_ecm_compare.csv: fitting metrics for multiple ECM candidates.

• *_drt.csv: DRT curve.

• *_fit.csv: original EIS, ECM reconstruction, and DRT reconstruction.

• *_summary.csv: single-sample summary.

• *_nyquist.png: Nyquist plot.

• *_bode.png: Bode plot.

• *_drt.png: DRT plot.

Batch jobs also output:

• batch_summary.csv

Local Debugging

Run the smoke test:

C:\ProgramData\Anaconda3\python.exe tests\smoke_test.py

Simulate an MCP batch call:

C:\ProgramData\Anaconda3\python.exe examples\debug_mcp_batch.py

Run the core algorithm from the command line:

C:\ProgramData\Anaconda3\python.exe -m eis_ecm_drt "test_cases/demo_eis/demo_eis.csv" `
  --ecm-model L-R0-RQ-W `
  --drt-lambda 0.01 `
  --n-tau 750 `
  --regularization-order 1 `
  --basis-function gaussian `
  --shape-factor 0.72 `
  --n-basis 220 `
  --boundary-suppression-factor 0.10 `
  --polarization-removal ignore_polarization `
  --fit-inductance `
  --no-plots

Python API

from eis_ecm_drt import DRTConfig, ECMConfig, analyze_file

result = analyze_file(
    "test_cases/demo_eis/demo_eis.csv",
    ecm_config=[ECMConfig(model="L-R0-RQ-W")],
    drt_config=DRTConfig(
        lambda_value=0.01,
        n_tau=750,
        regularization_order=1,
        basis_function="gaussian",
        shape_factor=0.72,
        n_basis=220,
        polarization_removal="ignore_polarization",
        boundary_suppression_factor=0.10,
        fit_inductance=True,
    ),
    make_plots=False,
)

print(result["ecm"].parameters)
print(result["drt"].tau, result["drt"].gamma)

License

This project is licensed under the MIT License. See LICENSE.

EIS ECM DRT MCP 中文

English | 中文

这是一个用于 EIS 数据批量分析的 MCP 服务。输入为 EIS 文件或文件夹，输出为 ECM 参数、DRT 曲线、拟合重构数据和图。

项目保持两层结构：

• eis_ecm_drt/：核心算法，包括列识别、ECM 拟合、DRT 反演、批量输出。

• eis_ecm_drt/mcp_server.py：MCP 薄接口层，只负责接收参数、校验用户选择、调用核心算法。

后续如果发现算法问题，直接改 eis_ecm_drt/ 里的源码，然后重启 MCP 服务即可。

功能

• 批量处理 .xlsx、.xls、.csv、.tsv、.txt

• 自动识别频率列、实部列、虚部列

• 自动统一虚部符号，输出采用 -Zimag 口径，同时保留物理虚部列

• ECM 支持四个主模型，也支持用户自定义等效电路表达式

• DRT 参数必须由用户显式选择

• 输出每个样本的 ECM 参数、DRT 曲线、拟合曲线、汇总 CSV 和可选 PNG 图

• 默认输出到桌面 EIS Analysis output 下的新子文件夹，不污染输入数据目录

从 GitHub 到安装

如果项目已经上传到 GitHub，先把代码克隆到本地：

git clone <你的 GitHub 仓库地址>
cd <项目文件夹>

如果已经有本地源码，直接进入项目根目录，例如：

cd C:\Users\wzd\Documents\电池软件

建议使用 Python 3.10 或更高版本：

py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e ".[mcp]"

也可以直接使用仓库自带的一键脚本。第一次运行会自动创建 .venv 并安装依赖：

.\run_mcp.cmd

命令行分析可以用：

.\eis-analysis.cmd "test_cases/demo_eis/demo_eis.csv" --ecm-model L-R0-RQ-W --no-plots

如果只是调试核心算法，也可以使用已有 Python 环境运行：

C:\ProgramData\Anaconda3\python.exe tests\smoke_test.py

启动 MCP

安装后可以直接启动：

.\.venv\Scripts\eis-ecm-drt-mcp.exe

也可以用模块方式启动：

.\.venv\Scripts\python.exe -m eis_ecm_drt.mcp_server

MCP 客户端配置示例：

{
  "mcpServers": {
    "eis-ecm-drt": {
      "command": "C:\\Users\\wzd\\Documents\\电池软件\\.venv\\Scripts\\python.exe",
      "args": ["-m", "eis_ecm_drt.mcp_server"],
      "cwd": "C:\\Users\\wzd\\Documents\\电池软件"
    }
  }
}

仓库里也提供了可复制修改的配置文件：

• examples/mcp_config_windows.json

• examples/mcp_config_macos_linux.json

配置完成后，在 MCP 客户端里刷新或重启连接。看到 eis-ecm-drt 这个 MCP 服务可用，就说明已经连上。

MCP 已连接后怎么用

连接成功以后，不需要手动运行命令行。你在支持 MCP 的客户端里提出需求，客户端会调用本项目暴露的 MCP 工具。

推荐使用流程：

1. 先调用 list_ecm_models，让用户选择 ECM 模型。

2. 再调用 list_drt_options，让用户选择或确认 DRT 参数。

3. 如果不确定输入文件格式，先调用 validate_eis 或 validate_eis_batch 检查列识别结果。

4. 单文件分析调用 analyze_eis_file。

5. 批量分析调用 analyze_eis_batch。

6. 打开输出目录里的 README_输出说明.txt 和 batch_summary.csv 查看结果。

最终结果默认在桌面：

D:\desktop\EIS Analysis output\batch_YYYYMMDD_HHMMSS\

每次分析都会在 EIS Analysis output 里面新建一个子文件夹。MCP 返回结果里也会包含 output_dir、readme_path 和 summary_path，其中 readme_path 是最推荐先打开看的说明文件。

用户可以这样对 MCP 客户端说：

请使用 eis-ecm-drt 分析 D:\desktop\EIS验证\温度估计_基础电池_txt。
ECM 模型我选择 L-R0-RQ-W。
DRT 参数使用推荐配置。
批量处理，自动识别频率、实部、虚部列，最终结果输出到桌面 EIS Analysis output 文件夹，并生成图。

如果想比较多个 ECM 模型，可以这样说：

请批量分析 D:\desktop\EIS验证\温度估计_基础电池_txt。
ECM 模型选择 L-R0-RQ、L-R0-2RQ、L-R0-RQ-W、L-R0-2RQ-W 四个都拟合并比较。
DRT 参数使用推荐配置。
最终结果输出到桌面 EIS Analysis output 文件夹。

注意：正式分析前必须明确 ECM 模型和 DRT 参数。MCP 不会自动替用户选择；如果调用时没有传确认字段，会直接报错。

MCP 工具

正式 MCP 暴露这些工具：

• list_ecm_models：列出四个主 ECM 模型和自定义模型写法。

• list_drt_options：列出 DRT 必选参数和推荐配置。

• validate_eis：验证单个文件或数组数据，并返回自动识别的列和清洗后的 EIS。

• validate_eis_batch：批量验证文件夹、通配符或文件列表。

• fit_ecm：对数组数据拟合一个用户已选择的 ECM 模型。

• calculate_drt：对数组数据按用户已选择的 DRT 参数计算 DRT。

• analyze_eis_file：分析一个 EIS 文件。

• analyze_eis_batch：批量分析文件、文件夹或通配符。

重要规则：

analyze_eis_file 和 analyze_eis_batch 不会替用户选择 ECM 或 DRT。调用前必须让用户选择：

• ecm_models：一个或多个 ECM 模型 ID 或自定义表达式

• drt_config：完整 DRT 参数字典

• ecm_models_confirmed_by_user: true：确认 ECM 模型是用户刚刚选择的

• drt_config_confirmed_by_user: true：确认 DRT 参数是用户刚刚选择或批准的

如果缺少这些选择或确认字段，MCP 会直接报错。

ECM 模型选择

主模型如下：

其中：

• L1：高频电感

• R0：欧姆内阻

• R1/R2：极化或电荷转移电阻

• CPE1/CPE2：常相位元件，输出参数为 CPE*_Q 和 CPE*_n

• W1：Warburg 扩散阻抗，当前实现只有一个参数

• ||：并联

• -：代码表达式中的串联分隔符，等价于电路图里的 +

用户也可以传自定义表达式，例如：

L1-R0-(R1||CPE1)-(R2-W1||CPE2)

DRT 参数选择

先调用 list_drt_options，让用户确认 DRT 参数。当前商业软件对齐后的推荐配置为：

{
  "lambda_value": 0.01,
  "n_tau": 750,
  "regularization_order": 1,
  "basis_function": "gaussian",
  "shape_factor": 0.72,
  "n_basis": 220,
  "polarization_removal": "ignore_polarization",
  "boundary_suppression_factor": 0.10,
  "nonnegative": true,
  "fit_r_inf": true,
  "fit_inductance": true,
  "weighting": "modulus"
}

说明：

• lambda_value：正则化强度

• n_tau：DRT 输出点数

• regularization_order：导数正则阶数，商业设置为一阶

• basis_function：基函数，推荐 gaussian

• shape_factor：Gaussian 基函数宽度；这里的 0.72 是本实现对商业曲线的等效校准值

• n_basis：内部求解的 Gaussian 基函数系数数量；推荐 220，输出仍为 n_tau=750 个点；设为 null 或命令行传 --n-basis 0 可回到旧的 750 系数全量求解

• polarization_removal：极化处理，推荐 ignore_polarization

• boundary_suppression_factor：边界极化抑制强度；推荐 0.10

• fit_inductance：是否拟合高频电感

• weighting：拟合加权方式，推荐 modulus

批量分析示例

MCP 调用 analyze_eis_batch 的参数示例：

{
  "inputs": ["D:/desktop/EIS验证/温度估计_基础电池_txt"],
  "recursive": false,
  "ecm_models": ["L-R0-RQ-W"],
  "ecm_models_confirmed_by_user": true,
  "drt_config": {
    "lambda_value": 0.01,
    "n_tau": 750,
    "regularization_order": 1,
    "basis_function": "gaussian",
    "shape_factor": 0.72,
    "n_basis": 220,
    "polarization_removal": "ignore_polarization",
    "boundary_suppression_factor": 0.10,
    "nonnegative": true,
    "fit_r_inf": true,
    "fit_inductance": true,
    "weighting": "modulus"
  },
  "drt_config_confirmed_by_user": true,
  "make_plots": true,
  "continue_on_error": true
}

一次比较多个 ECM 模型：

{
  "inputs": ["D:/desktop/EIS验证/温度估计_基础电池_txt"],
  "ecm_models": ["L-R0-RQ", "L-R0-2RQ", "L-R0-RQ-W", "L-R0-2RQ-W"],
  "ecm_models_confirmed_by_user": true,
  "drt_config": {
    "lambda_value": 0.01,
    "n_tau": 750,
    "regularization_order": 1,
    "basis_function": "gaussian",
    "shape_factor": 0.72,
    "n_basis": 220,
    "polarization_removal": "ignore_polarization",
    "boundary_suppression_factor": 0.10,
    "nonnegative": true,
    "fit_r_inf": true,
    "fit_inductance": true,
    "weighting": "modulus"
  },
  "drt_config_confirmed_by_user": true,
  "recursive": false,
  "make_plots": false
}

如果不传 output_dir，结果会写到：

D:\desktop\EIS Analysis output\batch_YYYYMMDD_HHMMSS\

如果没有 D:\desktop，会尝试用户桌面目录。总之默认不会写进输入数据文件夹，最终结果会放在桌面的 EIS Analysis output 目录下。

输入数据规则

推荐文件至少包含三列：

没有表头也可以。程序会根据数值特征识别频率列：

• 频率列通常全为正数

• 跨多个数量级

• 大致单调，例如 0.01 到 1000

• 找到频率列后，优先把后面相邻两列作为实部和虚部

虚部会统一成 -Zimag 输出口径：

• 低频处虚部为正：认为源数据已经是 -Zimag

• 低频处虚部为负：认为源数据是物理 Zimag，自动乘以 -1

内部计算仍使用物理复阻抗 Z = Zreal + j Zimag。

输出文件

每个样本会输出：

• README_输出说明.txt：输出目录说明，建议先打开这个文件

• *_ecm_params.csv：ECM 参数

• *_ecm_compare.csv：多个 ECM 候选模型的拟合误差对比

• *_drt.csv：DRT 曲线

• *_fit.csv：原始 EIS、ECM 重构、DRT 重构

• *_summary.csv：单样本摘要

• *_nyquist.png：Nyquist 图

• *_bode.png：Bode 图

• *_drt.png：DRT 图

批量任务额外输出：

• batch_summary.csv

文件名前缀来自原始 EIS 文件名。示例里的 cell_a 和 cell_b 只是 demo 假样本名，不代表真实电池编号。

本地调试

生成示例数据：

C:\ProgramData\Anaconda3\python.exe examples\make_demo_data.py

运行 smoke test：

C:\ProgramData\Anaconda3\python.exe tests\smoke_test.py

模拟 MCP 批量调用：

C:\ProgramData\Anaconda3\python.exe examples\debug_mcp_batch.py

直接命令行运行核心算法：

C:\ProgramData\Anaconda3\python.exe -m eis_ecm_drt "examples/data/*.csv" `
  --ecm-model L-R0-RQ-W `
  --drt-lambda 0.01 `
  --n-tau 750 `
  --regularization-order 1 `
  --basis-function gaussian `
  --shape-factor 0.72 `
  --n-basis 220 `
  --boundary-suppression-factor 0.10 `
  --polarization-removal ignore_polarization `
  --fit-inductance `
  --no-plots

商业软件对齐 loop

开发用脚本：

tools/commercial_alignment_loop.py

它会读取商业 DRT Excel，批量搜索 DRT 参数，并输出最佳配置：

C:\ProgramData\Anaconda3\python.exe tools\commercial_alignment_loop.py `
  --input-dir "D:\desktop\EIS验证\温度估计_基础电池_txt" `
  --commercial-drt "D:\desktop\EIS验证\基础电池_DRT_原始数据.xlsx" `
  --commercial-ecm "D:\desktop\EIS验证\2.ECM数据.xlsx" `
  --max-samples 60 `
  --candidate-preset refine `
  --evaluate-all

当前默认 DRT 参数来自该 loop 的 200 样本验证结果。

Python API

from eis_ecm_drt import DRTConfig, ECMConfig, analyze_file

result = analyze_file(
    "examples/data/cell_a.csv",
    ecm_config=[ECMConfig(model="L-R0-RQ-W")],
    drt_config=DRTConfig(
        lambda_value=0.01,
        n_tau=750,
        regularization_order=1,
        basis_function="gaussian",
        shape_factor=0.72,
        n_basis=220,
        polarization_removal="ignore_polarization",
        boundary_suppression_factor=0.10,
        fit_inductance=True,
    ),
    make_plots=False,
)

print(result["ecm"].parameters)
print(result["drt"].tau, result["drt"].gamma)

许可证

本项目使用 MIT License，见 LICENSE。