Sezzlee Excel MCP server

@sezzlee/excel-mcp

A standalone MCP server that reads local Excel files by default. Opt-in writing creates immutable output versions without changing the source.

Reads .xlsx, .xlsm and .csv, sandboxed to one folder. Sandboxing, the document cache, the error envelope, the cursor codec and the tool registration layer come from @sezzlee/file-core.

Documentation: https://docs.sezzlee.app/docs/excel-mcp/introduction — a tutorial, task guides, and the tool, error-code and limit reference generated from this package.

Quick start

The server takes the folder it is allowed to read as its only argument, as an absolute path. Nothing outside that folder can be read.

{
  "mcpServers": {
    "excel": {
      "command": "npx",
      "args": ["-y", "@sezzlee/excel-mcp", "/Users/me/sheets"]
    }
  }
}

With Claude Code:

claude mcp add excel -- npx -y @sezzlee/excel-mcp /Users/me/sheets

Requires Node.js 22 or 24 on macOS (x64, arm64), glibc Linux (x64, arm64) or Windows x64; file access goes through a native module with no JavaScript fallback.

Author reports

Append --write <relative-output-directory> to enable writing inside the workbook root. Call prepare_edit with the exact source and changes, then pass its ready preparationId to edit_workbook. create_workbook can publish values and ordered presentation changes together. Continue from a returned version or branch from an older retained one.

Ready returns publication: not_published and a nextAction with the tool and arguments required to save the edit.

Authoring supports composable number/date/time/currency/percentage formats, font/fill/border/alignment changes, dimensions, frozen panes, visibility, basic print layout and safe merge/unmerge. Merging rejects non-anchor contents unless discarding them is explicitly requested. Scalar writes remain typed; formula-looking text stays text.

Explicit formula write/fill supports ordinary A1, mixed/absolute, sheet and structured table references. Table operations cover creation, renaming, header changes, growth/shrink, calculated columns, totals, filters and conversion to a range. New table styles are SezzleeBlue or none; conversion refuses unsupported affected styles and dependencies. Shrink preserves excluded values unless clearing is explicitly requested.

Table range resizing changes the row extent while retaining header position and width. Structural width changes use the explicit worksheet column operations first. Saved filter/sort criteria that need an unsupported transformation cause a refusal.

Bulk jobs can finish each selected output with ordered presentation/formula changes before atomic publication. A failed group leaves no partially finished report. Independent groups retain their successful outputs and report partial status; identical retries reuse durable results.

Authoring writes formulas without fabricated cached results and reports required recalculation. Use the separate calculate_workbook tool to evaluate the explicitly supported formula subset and save typed caches in a new version. Dynamic spilling arrays and new external workbook formula links remain outside this authoring profile. See Phase 5 acceptance and the Phase 6 contract.

Explicit formula calculation

In writing mode, calculate_workbook({source: {filePath, versionId}}) recalculates the selected workbook from its actual inputs. It returns a new immutable version, a calculation summary and up to 20 cell results. Longer string results and additional cells remain available in the saved workbook; the response reports omissions. Formula text, supported formatting, tables and unrelated package parts are preserved.

The bounded-excel-v1 engine supports ordinary arithmetic, percent, concatenation and comparisons; SUM, AVERAGE, MIN, MAX, COUNT, COUNTA, COUNTBLANK, IF, IFERROR, AND, OR, NOT, SUMIF, COUNTIF, ABS, ROUND, ROUNDUP, ROUNDDOWN, exact VLOOKUP, exact MATCH and scalar INDEX. References include rectangular A1 ranges, quoted/cross-sheet references, absolute static names with sheet scope and supported Phase 5 structured table references. Dates retain the workbook's numeric 1900/1904 serial system. Literal formula-looking text stays text.

calculation.complete describes whether every formula was evaluated within this subset; typed Excel errors count as evaluated results. Unsupported formulas, cycles and unavailable dependencies have distinct diagnostics and no retained stale caches. cacheStatus is current or partial. recalculationRequired is false for complete current results and true when unavailable results still require calculation. The separate recalculationOnOpen: true describes the saved file's conservative Excel on-open flags; current server results remain usable without another read or calculation. Calculate before applying sheet/workbook protection. Existing protection and other preservation blockers are identified in calculation refusals. A later ordinary edit invalidates formula caches again.

Shared formulas are reported unavailable with caches cleared. Array/data-table groups, iterative calculation, precision-as-displayed, R1C1 formulas and unsupported preservation profiles are refused without publishing. Volatile functions, external workbooks, UDFs, dynamic arrays, approximate lookups, wildcard lookups, formula-defined names and relative name anchors are unsupported. SUMIF requires equally shaped ranges. Localized date/currency text coercion is outside the numeric-text subset.

Calculation is bounded to 128 sheets, 100,000 stored cells, 10,000 formula cells, 10,000 names, 8,192 formula characters, 100,000 cells per expanded range, combined depth 128 and 1,000,000 work steps. Limit exhaustion preserves the source and all retained outputs. Calculation is a separate version operation after a bulk job; it does not change that job's atomic publication boundary. No Excel installation or additional runtime package is required.

Expert report authoring

The Phase 7 profile composes the operations below through create_workbook, prepare_edit, edit_workbook and bulk finishing. Every change produces a new immutable .xlsx; a failure publishes no partial version. The implementation plan and acceptance status distinguish implementation from verification.

Family	Operations and support
Names and templates	define_name, delete_name, write_named_range. Static rectangular A1 targets, workbook or sheet scope, quoted sheet names and exact typed input dimensions. Replacement requires overwrite:true; deleting a potentially referenced name refuses. Built-in names and table/cell-name collisions refuse.
Validation	set_validation, remove_validation. Inline lists, whole/decimal/date/text-length comparisons and custom formulas. Date bounds are workbook serials. These are interactive Excel rules; the server does not enforce them on every later value write. Removal selects one stored rule by its complete range or by the ranges get_data_validations reports for it; replacement selects its complete single range.
Conditional formats	set_conditional_format, remove_conditional_format. Comparison/expression rules, differential font/fill appearance, explicit priority and stopIfTrue. Replace an occupied priority explicitly. Unsupported extension rules are retained by unrelated edits, not silently converted.
Content	set_hyperlink, set_note, set_image and their matching remove_* operations. Existing internal A1/name links or HTTPS links without credentials; plain legacy notes; embedded PNG/JPEG with cell anchors. Existing cell values survive hyperlink changes unless display explicitly replaces them; an empty hyperlink cell gets its target as a text label. Removing an unshared image/chart also removes its unreferenced package content.
Charts	set_chart, remove_chart. Column, bar, line and pie charts; title, placement and explicit category/value ranges. Replacement rebuilds the selected object. Literal-source caches are checked against their dependencies; formula sources omit invented caches and report refresh. Unsupported outgoing object dependencies refuse removal/replacement.
Pivots	set_pivot creates or explicitly refreshes/replaces a real PivotTable, its private cache/records and saved results. One categorical row field; up to eight sum/count/min/max measures. Count counts nonblank values; numeric measures ignore nonnumeric values. Source range includes unique text headers. Formula and ISO-date cells require an explicit value/text/serial conversion first. Shared caches, advanced pivot extensions and external sources are outside the refresh profile.
Protection	format_cells accepts style.protection; protect_sheet and protect_workbook author sheet/structure protection. Optional legacy protection passwords are printable ASCII, one to 15 characters. This is not file encryption. Start continuation with authenticated unprotect_workbook/unprotect_sheet operations for every locked target. Strong-hash, revision/window protection, encrypted, signed and macro-enabled editing remain refused.
Recurring reports	Use the existing version-pinned bulk job with replace_values and expert finishing. Shorter datasets clear the old tail; the period belongs in an explicit named text target. Identical jobs reuse durable completion. Formula calculation remains a separate immutable operation before final protection.

Advanced object sources are bounded to 100,000 cells. A chart has at most 16 series and 10,000 points per series; pie charts have one series. A sheet has at most 64 pivots with 10,000 row groups per pivot, 256 validation rules, 256 conditional rules and 4,096 notes or authored links. Named targets are bounded to 4,096 per workbook. Drawings have at most 256 anchored objects. An embedded image has at most 5 MiB, 16,777,216 pixels and an 8,192-pixel side; total embedded media is bounded to 20 MiB. Existing transaction, input, output and cell budgets also apply.

Data/source changes invalidate affected chart caches and mark affected pivot caches invalid with refresh requested. Unrelated literal-source caches remain intact. Copy/move, sheet operations and row/column changes update supported references, ranges and anchors; affected pivot, VML, extension and other unsupported dependency profiles refuse atomically. Unknown retained parts are not a promise of arbitrary structural editing.

Reading is a separate capability: the existing tools inspect names, validations, conditional formats, images and charts, and read saved pivot result cells. Dedicated pivot-definition and legacy-note reader tools are not added by this authoring profile. Macros are never executed.

Independent Calc checks cover values, pivot/cache consistency, chart types/series, effective conditional fills and rule order, links, notes, images and protection. Calc does not retain stopIfTrue on export; this consumer limitation is reported separately. The original .xlsx flag is independently inspected and schema-validated. No desktop Excel UI acceptance is claimed.

Tools

Numeric text coercion is limited to plain decimal/scientific strings. Formatted numeric, percentage, currency and date text that requires another conversion profile is reported unsupported, including in direct COUNT arguments and numeric criteria. It is not reported as an invented Excel error or hidden by IFERROR. Ordinary nonnumeric text retains the documented Excel error behavior.

Tool	What it does
list_workbooks	Lists readable files under the root; the filePath it returns is passed to other tools verbatim
describe_workbook	Sheets and their kind (worksheet or chart sheet), used ranges, counts of merges, validations, tables, formulas, images and charts, defined names
profile_sheet	Bounded type and quality profiles with reusable column specifications
read_sheet	A cell range as a compact grid: hoisted column headers plus row arrays
aggregate_sheet	Grouped summaries, calendar and numeric buckets, bounded pivots, conditional metrics and exact percentiles
query_result	Exact filtering, column selection and stable paging over a retained complete aggregate snapshot
find_in_sheet	Cells whose value or formula matches a query; without a sheet, in every worksheet
get_tables	Excel Tables: range, header and totals rows, column names and letters
get_data_validations	Validation rules, one entry per stored rule with its ranges
get_conditional_formats	Conditional formatting rules as predicates
get_merged_ranges	Merged cell ranges
get_images	Drawing and in-cell pictures: drawing name, anchor, alt text, size and extension. Charts belong to get_charts
get_charts	Charts: type, title, axes (incl. secondary, scale, format), series refs/points, trendlines, hidden series, pivot source. Chart sheets included

Every argument, error code and limit is listed in the reference.

How text is read as numbers and dates

A CSV holds only text, and a workbook may store numbers and dates as text too. read_sheet and default find_in_sheet return that text as written. aggregate_sheet reads it as a number or a date only where a metric or a where operand needs one, and decides the format per column from every value in the range: the decimal and thousands separators (1.234,50, 1,234.50, 1 234,50, 1'234.50), and whether slash dates put the day or the month first. The marks or order that read the most values win. When the winners read some value differently (1.234, 01/02/2023) the column is ambiguous: none of those values is read, and a warning names the columns entry that settles it. Accounting parentheses, a leading or trailing % (read as a ratio) and a currency symbol or code are understood; dotted dates are day first, and Turkish and English month names are read.

A digit run with a leading zero or more than 15 digits is an identifier and is never summed unless columns declares the column a number. A column whose amounts name more than one currency is summed as written and reported. Every value a call could not read, compare or sum is counted in warnings with examples, and readAs reports how each column's text was read. A time-only number format (h:mm, hh:mm:ss AM/PM) is returned as HH:mm:ss; elapsed [h], [m] and [s] formats return {"durationSeconds": number} and can be summed in seconds.

Which row is the header row

A call that names no headerRow reads by the row a declared table or the autofilter heads; failing those, by the first of the top 20 rows of the used range whose filled cells are all text, at least two of them and none merged across columns, provided no row above it holds a number, a date or another non-text cell; failing that, by row 1. A header sits above its data, so a text-only data row lower down, such as a row of --- placeholders, is never taken for one. The response says which (headerRowSource: declared, scanned or default). The scan always covers the whole used range, so a call reading a few rows or a single column gets the same header row as one reading the sheet, and a title band above the columns is skipped without the caller knowing it is there. A CSV always reads row 1. headerScan: true asks for a strict detection: it refuses when two rows qualify or none does. A header cell holding a number or a boolean names its column by its text, so a year heading is addressable as "2008". When the default row 1 holds no text at all, the read warns header_row_unnamed, even for an explicit range, because those values then name the columns; headerRow: 0 reads that row as data.

Warnings

A response's warnings is a list of { code, message, column? }. Branch on code; message is for a person and its wording may change. column is the letter a warning is about, when it is about one.

Code	Raised when
csv_preamble_ignored	A sep= line names another delimiter than the one passed
csv_blank_first_record	The first CSV record is blank and stays the header
table_missing_names	A declared table has columns without names
header_row_mismatch	headerRow differs from the row a table or the autofilter declares
header_row_unnamed	headerRow names no column while another top row does
header_only_range	A read_sheet range holds only the header row
uncached_formulas	Formula cells carry no cached value
ambiguous_decimal	Values read differently with a decimal point and a decimal comma
locale_separator_conflict	locale reads values as other numbers than the column's own marks
ambiguous_day_order	Dates read either day first or month first
mixed_date_order	Slash dates read month first while dotted dates read day first
distinct_lower_bound	A profiled column has more distinct values than are counted
no_majority_type	No type holds a strict majority of a profiled column
identifier_text	A profiled column looks like identifiers and stays text
no_reusable_date_format	No single date format reads a profiled column's dates
prefix_sample	A profile describes only the first rows
columns_not_profiled	Columns past maxColumns were not profiled
mixed_units	A metric adds plain numbers, fractions or durations
mixed_currencies	A metric adds different or unlabelled currencies
case_variant_groups	Groups differ only by case or accent
uncomparable_cells	where cells could not be compared with the operand
ungrouped_cells	Cells could not be read for a grouping key
currencies_added	A column's amounts are written in more than one currency
unread_numbers	Text cells do not read as numbers and are left out of totals
identifier_cells	Cells look like identifiers and are left out of totals
unread_booleans	Cells do not read as booleans and are left out of boolean metrics
derived_division_by_zero	A derived metric divided by zero in a group and is null there