Battery Analyzer

An MCP (Model Context Protocol) server that exposes Dunn and GITT battery analysis calculations to AI assistants like Cursor and Claude Desktop.

This package is fully standalone — calculation code is copied here and does not import from battery-analyzer/.

Tools

Tool	Description
list_battery_methods	List available methods and expected Excel input formats
list_data_files_tool	List .xlsx files in the data folder
calculate_dunn	Run Dunn method (K1, K2, b values) on cyclic voltammetry data
calculate_gitt	Run GITT method (diffusion coefficients) on titration data

Data folder

Place input Excel files in:

battery-analyzer-mcp/data/

Tools take only the file name (not a full path), for example dunn_method_data.xlsx. The .xlsx extension is optional.

Results are saved in the same data/ folder next to the input file.

Override the data folder with the BATTERY_ANALYZER_DATA_DIR environment variable if needed.

Input file formats

Dunn method

No header row in the Excel file:

	Col 1+
Row 0	Scan rates (V/s)
Row 1	(unused)
Row 2+	Voltage (V) in col 0	Current (A) per scan rate

GITT method

• Skip first skip_rows metadata rows (default: 6)
• Column 0: time (s)
• Column 1: voltage (V)

Install

Requires Python 3.10+ and uv:

cd battery-analyzer-mcp
uv sync

Run locally(if needed in case of local mcp client)

uv run battery-analyzer-mcp

Or with MCP Inspector for development:

uv run mcp dev src/battery_analyzer_mcp/server.py

Cursor MCP configuration

Claude Desktop configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "battery-analyzer": {
      "command": "uv",
      "args": [
        "--directory",
        "<absolute path to your directory>/battery-analyzer-mcp",
        "run",
        "battery-analyzer-mcp"
      ]
    }
  }
}

Restart Claude Desktop after saving.

Troubleshooting

Failed to spawn process: No such file or directory

Claude Desktop / Cursor could not find the command binary. GUI apps use a limited PATH and usually cannot resolve bare uv. Fix:

1. Run cd battery-analyzer-mcp && uv sync to create .venv/
2. Use the full path to .venv/bin/battery-analyzer-mcp as the command (see Option A above)
3. Or use the full path to uv (e.g. /Users/pankaj/anaconda3/bin/uv) instead of just "uv"

Example tool calls

List methods:

list_battery_methods()

List available input files:

list_data_files_tool()

Dunn calculation:

calculate_dunn(file_name="dunn_method_data.xlsx")

GITT calculation:

calculate_gitt(
  file_name="GITT_67.xlsx",
  skip_rows=6,
  L=1e-4,
  tau=1800
)

Output

Each calculation tool returns a compact JSON response (under Claude Desktop's 1 MB MCP limit):

• results_path — path to the saved Excel file (*_dunn_results.xlsx or *_gitt_results.xlsx)
• message — status message
• preview — first rows of core results (Dunn: Voltage, K1, K2, b only)
• plots — plot titles and series metadata only (no x/y coordinates)
• summary — method-specific metadata
• note — explains that full data is in the Excel file

Full numeric results and all columns are always written to results_path. Open that Excel file for complete data and plotting.

Results Excel files are written to the data/ folder next to the input file.

Dependencies

• mcp[cli] — MCP Python SDK
• pandas, numpy, scipy, openpyxl — calculation and Excel I/O