Ironcalc

PyPI Python 3.13+ License: MIT Tests

MCP server for the IronCalc spreadsheet engine. Create, read, edit, and save xlsx files through the Model Context Protocol.

Covers the full surface of the IronCalc Python SDK - everything you can do with ironcalc in Python, you can do through MCP.

Motivation

I was really inspired by 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 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

uvx ironcalc-mcp

Claude Code

claude mcp add ironcalc -- uvx ironcalc-mcp

Claude Desktop / Cursor

Add to your MCP config:

{
  "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.

Contributing

Contributions are welcome! To get started:

git clone https://github.com/yolonir/ironcalc-mcp
cd 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