ferroxl-mcp
A Model Context Protocol server that lets an AI agent
read and edit Excel .xlsx and .xlsm files.
It is backed by ferroxl, a feature-parity port of openpyxl 3.1.5.
Installation
Prebuilt archives for Linux, macOS and Windows are attached to each GitHub release.
Running
The server speaks MCP over stdio, so an agent launches it directly:
--root bounds every path the tools may touch. Without it, $FERROXL_ROOT is used, and
without that the working directory. Paths in tool arguments are resolved inside that root,
and a path that escapes it is refused rather than followed. The root is created if it does
not exist.
This is a convenience that keeps an agent inside a directory you chose, not a security sandbox: a caller that can launch this process can already do whatever it likes.
$ ferroxl-mcp --help
ferroxl-mcp 0.2.0 - a Model Context Protocol server for Excel workbooks
USAGE:
ferroxl-mcp [--root <directory>]
OPTIONS:
--root <directory> Bound every path the tools may touch. Defaults to
$FERROXL_ROOT, then the working directory.
-h, --help Print this help and exit.
-V, --version Print the version and exit.
The server speaks JSON-RPC 2.0 over stdio, one message per line.
Configuring an agent
Tools
50 tools, in six groups. To see the arguments each one takes, list them from your agent, or
read crates/ferroxl-mcp/src/tools.rs.
Inspection & Reconciliation — list_sheets, describe_sheet, read_cells, read_range_markdown,
read_formulas, get_column_by_header, trace_precedents, trace_dependents,
check_circular_references, audit_health, diff_workbooks, evaluate_formula,
recalculate_workbook, reconcile_ranges, add_data_bar, add_icon_set, add_table,
describe_table, set_gradient_fill, search_values, summarize_range, list_comments,
list_named_ranges, export_csv.
Structure — create_workbook, add_sheet, remove_sheet, rename_sheet,
merge_cells, unmerge_cells, freeze_panes, set_auto_filter, add_named_range.
Values — set_cell, write_cells, write_range, append_row, clear_cells. Formulas go through
the same tools as values; write_range writes 2D matrices in one call to optimize context-window token usage.
Layout — set_column_width, autofit_columns, set_row_height, set_header_footer, add_hyperlink.
Formatting — style_cells, set_number_format, add_data_validation,
add_conditional_format. Supports standard format strings and Indian numbering presets ("indian", "lakhs", "crores", "inr", "rupees", "inr_lakhs").
Media and annotations — add_chart, add_image, add_comment.
Every tool returns a one-line summary as well as structured JSON. The summary is what a model reads first, so it is written to be the useful part: the count, the names, the coordinates. Where a list could be arbitrarily long — a cell with thousands of dependents — the summary names the first dozen and gives the count, because the count is what changes the next decision and the list would only consume the context window needed to make one.
The tracing and auditing tools answer what openpyxl cannot at all: which cells feed a cell, which
formulas would go stale if one changed, every circular reference as a closed path, forensic overwrites
of formulas with hardcoded constants (diff_workbooks), and cross-workbook reconciliation joins (reconcile_ranges).
Values
A tool that writes a value takes JSON, with a deliberately narrow mapping so a model does not have to learn a wrapper object:
| JSON | Stored as |
|---|---|
a string beginning = |
a formula |
"2010-01-18" or "18-01-2010" |
a date |
"2010-01-18T14:15:20" or "18-01-2010 14:15:20" |
a timestamp |
"14:15:20" |
a time of day |
"50%" |
the number 0.5 |
| a number | a number |
true / false |
a boolean |
null |
an empty cell |
| anything else | text |
Values come back with their type spelled out, so a formula is never confused with the text it evaluates to:
Recalculation & Formula Engine
The server can evaluate formulas in two ways:
evaluate_formula: Sandbox formula evaluation against active sheet context without saving.recalculate_workbook: Evaluates formulas in multi-pass dependency order (up to 50 passes) and caches computed results into<v>tags, returning a structured audit report of computed and unresolved formulas. This enables downstream consumers (Pandas, openpyxldata_only=True, web viewers) to read evaluated numbers.
The formula engine supports 44 standard and financial functions, including VLOOKUP, XLOOKUP, INDEX, MATCH, SUMIFS, COUNTIFS, SUMIF, COUNTIF, and handles whole-column ranges (A:A) and single-quoted Unicode sheet names.
Errors
A tool that ran and failed returns isError: true with the message in content, so the
model can read what went wrong and correct its call. Only an unknown method or tool is a
JSON-RPC error (-32601). A misspelled argument is rejected rather than ignored, because a
tool that silently drops an argument is worse than one that refuses.
License
MIT.