Battery Analyzer MCP Server

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