# Battery Analyzer MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/docs/getting-started/intro) 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](https://docs.astral.sh/uv/):

```bash
cd battery-analyzer-mcp
uv sync
```



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

```bash
uv run battery-analyzer-mcp
```

Or with MCP Inspector for development:

```bash
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`:

```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