ironcalc-mcp

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

Built on the typed high-level API in IronCalc 0.8.3. It exposes workbook editing, formulas, styles, structure, names, conditional formatting, and xlsx persistence 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 (56)

Workbook

Tool	Description
`create_workbook`	Create an empty workbook with locale, timezone, and formula language
`load_workbook`	Load an xlsx file
`save_workbook`	Save to xlsx
`get_workbook_info`	Get metadata, theme, sheets, dimensions, states, and colors
`set_workbook_properties`	Update name, locale, timezone, language, or theme
`undo`	Undo the latest action
`redo`	Redo the latest undone action

Cells and ranges

Tool	Description
`get_cell`	Get content, formatted value, and type
`get_cells`	Read non-empty cells from an inclusive range
`set_cell`	Set a value or formula
`set_cells`	Batch-write cells with one evaluation pass
`set_array_formula`	Set an array formula over a result area
`clear_range`	Clear contents, formatting, or everything
`paste_csv`	Paste tab-delimited rows into a range

Sheets

Tool	Description
`add_sheet`	Create a sheet
`delete_sheet`	Delete a sheet
`rename_sheet`	Rename a sheet
`set_sheet_color`	Set the tab color
`duplicate_sheet`	Duplicate a sheet
`hide_sheet` / `unhide_sheet`	Change sheet visibility
`move_sheet`	Reorder a sheet
`set_grid_lines`	Show or hide grid lines

Rows and columns

Tool	Description
`insert_rows` / `delete_rows`	Insert or delete rows
`insert_columns` / `delete_columns`	Insert or delete columns
`move_rows` / `move_columns`	Move a contiguous row or column block
`set_column_width`	Size one column or an inclusive range
`set_row_height`	Size one row or an inclusive range
`set_rows_hidden` / `set_columns_hidden`	Hide or unhide inclusive ranges
`set_frozen_rows` / `set_frozen_columns`	Set frozen panes
`auto_fill_rows` / `auto_fill_columns`	Extend values and formulas from a source area

Formatting

Tool	Description
`get_cell_style`	Get font, fill, border, alignment, and number format
`set_cell_style`	Update selected style properties on a cell or range
`set_range_border`	Apply inner, outer, side, or full borders

Named styles and conditional formatting

Tool	Description
`list_named_styles` / `get_named_style`	Inspect named styles
`create_named_style` / `update_named_style` / `delete_named_style`	Manage named styles
`apply_named_style`	Apply a named style to a range
`list_conditional_formats`	List conditional formatting rules
`add_conditional_format` / `update_conditional_format` / `delete_conditional_format`	Manage rules
`raise_conditional_format_priority` / `lower_conditional_format_priority`	Reorder rules

Defined names

Tool	Description
`list_defined_names`	List workbook- and sheet-scoped names
`create_defined_name`	Create a defined name
`update_defined_name`	Rename, re-scope, or update a defined name
`delete_defined_name`	Delete a defined name

Contributing

Prerequisites: uv and just.

git clone https://github.com/yolonir/ironcalc-mcp
cd ironcalc-mcp
just init

just init syncs the locked environment and installs the deterministic prek commit hook.

just test                      # Behavioral tests
just quality-check             # Ruff, mypy, and ty
just quality-check src/path.py # Targeted quality checks
just precommit                 # Run all commit-time hooks
just format                    # Format and apply safe lint fixes

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

License

MIT