# ironcalc-mcp

[![PyPI](https://img.shields.io/pypi/v/ironcalc-mcp)](https://pypi.org/project/ironcalc-mcp/)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://pypi.org/project/ironcalc-mcp/) 
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Tests](https://github.com/ironcalc/IronCalc/actions/workflows/test.yml/badge.svg)](https://github.com/ironcalc/IronCalc/actions/workflows/test.yml)

MCP server for the [IronCalc](https://www.ironcalc.com/) spreadsheet engine. Create, read, edit, and save xlsx files through the Model Context Protocol.

Covers the full surface of the [IronCalc Python SDK](https://pypi.org/project/ironcalc/) - everything you can do with `ironcalc` in Python, you can do through MCP.

## Motivation

I was really inspired by [paper.design](https://paper.design/)'s real-time MCP workflow, where exposing a design tool via MCP enables custom, extensible agent workflows that feel native rather than bolted on.

Current AI-spreadsheet integrations (like Claude's cowork mode for Excel) add an unnecessary layer of abstraction - the agent writes Python code that manipulates Excel, instead of talking to the spreadsheet directly. This MCP server removes that indirection. Agents read cells, write formulas, and get evaluated results in one hop. No codegen middleman, no openpyxl glue scripts.

Huge thanks to the [IronCalc](https://github.com/ironcalc/IronCalc) contributors - their Python SDK API is so clean that this entire MCP server is basically thin wrappers. The hard work is all theirs.

**Current limitation:** the server works with an in-memory workbook - load a file, edit it, save it back. There's no real-time streaming to a running IronCalc UI yet. The engine already has a diff queue for syncing, so the plumbing is there. If IronCalc adds a WebSocket bridge to their web app, we can wire up live sync and get a true reactive workflow - agent edits appearing in the browser as they happen.

## Quick start

```bash
uvx ironcalc-mcp
```

### Claude Code

```bash
claude mcp add ironcalc -- uvx ironcalc-mcp
```

### Claude Desktop / Cursor

Add to your MCP config:

```json
{
  "mcpServers": {
    "ironcalc": {
      "command": "uvx",
      "args": ["ironcalc-mcp"]
    }
  }
}
```

## Examples

**Build a spreadsheet from scratch**
```
Create a budget with formulas and save it
```

**Audit an existing xlsx for errors**
```
Load quarterly_report.xlsx and find all #NAME?, #REF!, #VALUE! errors. Tell me which formulas are broken and why.
```

**Fix broken cross-sheet references**
```
The P&L sheet was renamed but formulas in the DCF sheet still reference the old name. Find and fix all broken references.
```

**Build a financial model**
```
Create a 5-year DCF model with revenue assumptions in one sheet, P&L in another, and free cash flow calculation in a third. Use =NPV() and =IRR() for valuation.
```

**Analyze and transform data**
```
Load sales_data.xlsx, add a column with running totals, insert a summary row at the bottom, and save.
```

## Available tools (21)

### Workbook

| Tool | Description |
|------|-------------|
| `create_workbook` | Create a new empty workbook. Params: `name`, `locale`, `timezone`, `language` |
| `load_workbook` | Load workbook from an xlsx file. Params: `file_path`, `locale`, `timezone`, `language` |
| `save_workbook` | Save workbook to xlsx. Params: `file_path` (optional, defaults to load path) |
| `get_workbook_info` | Get sheets list, dimensions, state, colors |

### Cells

| Tool | Description |
|------|-------------|
| `get_cell` | Get content, formatted value, and type of a single cell |
| `get_cells` | Read a rectangular range of cells |
| `set_cell` | Set a cell's value or formula (prefix with `=`) |
| `set_cells` | Batch set multiple cells in one call |

### Sheets

| Tool | Description |
|------|-------------|
| `add_sheet` | Create a new sheet (auto-named or custom name) |
| `delete_sheet` | Remove a sheet by index |
| `rename_sheet` | Rename a sheet |
| `set_sheet_color` | Set the tab color (hex) |

### Structure

| Tool | Description |
|------|-------------|
| `insert_rows` | Insert rows at a position |
| `delete_rows` | Delete rows at a position |
| `insert_columns` | Insert columns at a position |
| `delete_columns` | Delete columns at a position |
| `set_column_width` | Set column width in points |
| `set_row_height` | Set row height in points |
| `set_frozen_rows` | Freeze top N rows |
| `set_frozen_columns` | Freeze left N columns |

### Formatting

| Tool | Description |
|------|-------------|
| `get_cell_style` | Get font, fill, border, alignment, number format |

> `set_cell_style` is not yet available — the IronCalc Python binding exposes style properties as read-only. PRs welcome to add `#[pyo3(get, set)]` upstream.

</details>

## Contributing

Contributions are welcome! To get started:

```bash
git clone https://github.com/ironcalc/IronCalc
cd IronCalc/ironcalc-mcp
uv sync
uv run ironcalc-mcp
```

Please create a new branch for your changes and open a pull request against `main`. Pls keep them focused.

## License

MIT
