Add a data-validation input rule to a range.

validation_type:

• 'list': in-cell dropdown; pass options=["Yes","No"] (literal values) or formula='=$F$1:$F$5' to source the choices from cells.

• 'whole', 'decimal', 'date', 'text_length': pass operator (between, notBetween, equal, notEqual, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual) and values (two for between/notBetween, otherwise one). Dates are ISO strings like '2026-01-31'.

• 'custom': pass formula, e.g. '=ISNUMBER(A2)'.

error_message customizes the rejection dialog; prompt shows a tooltip when the cell is selected. Rules take effect when the file is used in Excel.

Sort the rows of a range by one column's values.

by_column is the sheet column letter (e.g. 'B') and must fall inside the range. Set has_header=true if the range's first row is a header to keep in place. Numbers and dates sort before text; blank cells always sort last. Only values move — formatting stays put, and formulas move as text (their relative references are NOT adjusted). For multi-key sorts, call once per key from least to most significant column (the sort is stable).

Add Excel's filter dropdowns to a data range (one filter per sheet).

range should cover the header row plus data, e.g. 'A1:D50'; omit it to use the sheet's whole used range. Pass remove=true to clear the sheet's filter. This adds the filter UI — choosing filter values happens in Excel.

Delete duplicate rows within a range, keeping each first occurrence.

columns lists the sheet column letters that decide uniqueness, e.g. ["A","C"] (each must fall inside the range); omit to compare whole rows. Text comparison ignores case, like Excel's Remove Duplicates. Set has_header=true to leave the range's first row in place. Remaining rows shift up and the freed rows at the bottom are cleared. Only values are compared and moved, not formatting.

Attach a comment (note) to a cell. Replaces any existing comment.

List all comments on a sheet with their cells, text, and authors.

Remove the comment from a cell.

Turn a cell into a hyperlink.

url can be external ('https://example.com', 'mailto:a@b.com') or internal to the workbook with a '#' prefix ('#Sheet2!A1'). display sets the cell text; if omitted, an empty cell shows the url. The cell is styled as a link (blue, underlined).

Remove the hyperlink from a cell. The cell value and formatting stay.

Read one cell's value. cell is A1 notation, e.g. 'B2' or 'Sheet1!B2'.

Returns the stored value; for formula cells this is the formula text (e.g. '=SUM(A1:A5)'), since files edited outside Excel hold no cached result.

Write a value to one cell. Strings starting with '=' are stored as formulas.

Pass null to clear the cell. Dates should be ISO strings; they are stored as text unless the cell already has a date number format.

Read a rectangular range as a 2D array (rows of cell values).

Large ranges are truncated at 10,000 cells; the response then includes truncated=true and next_range to continue reading from.

Write a 2D array of values starting at start_cell (top-left corner).

values is a list of rows, e.g. [["Name","Age"],["Ana",31]]. Strings starting with '=' are stored as formulas. null leaves a gap (clears that cell).

Read a whole sheet's used range. Omit sheet to read the active sheet.

With first_row_is_header=true, returns records as a list of dicts keyed by the header row. Truncates at 10,000 cells like read_range.

Append rows after the last used row of a sheet (like adding to a table).

values is a list of rows. Omit sheet to use the active sheet.

Clear values (not formatting) from every cell in a range.

Get the bounding range of used cells on a sheet, e.g. 'A1:F120'.

Recalculate all formulas using a hidden desktop Excel instance and cache the results in the file, so read_calculated_range can return computed values.

Saves the session to disk first (flushing pending edits), then opens the file invisibly in Excel, recalculates, and saves. The in-memory session keeps formulas as text; only the file on disk gains cached results. Requires Microsoft Excel on Windows (uv sync --extra com).

Read computed formula results (cached values) from the saved file.

Reads the last saved copy on disk, so run recalculate_workbook first — formula cells that were never calculated come back null with a hint. Non-formula cells return their stored values as usual. Truncates at 10,000 cells with a next_range cursor, like read_range.

Embed a chart in a sheet.

chart_type: bar, bar_horizontal, line, pie, scatter, area. data_range holds the value column(s); with data_includes_headers=true (default) the first row provides the series names. categories_range is the label column/row for the axis (or the slice labels for pie). For scatter, categories_range is required and supplies the shared x-values (no header); each data_range column becomes one y-series.

position is the cell of the chart's top-left corner (e.g. 'E2'); it defaults to two columns right of the data. Data and chart may be on different sheets ('Summary!E2'). width_cm/height_cm default to 15 x 7.5.

List the charts embedded in a sheet, with the index used by delete_chart.

Delete a chart by its index (see list_charts). The data is unaffected.

Set font properties on every cell in a range. Only the properties you pass are changed; others are preserved.

color accepts hex ('#FF0000') or names like red, blue, white, dark_blue.

Set a solid background fill on every cell in a range.

color accepts hex ('#FFFF00') or names like yellow, light_blue, light_gray. Pass 'none' to remove the fill.

Draw borders on a range.

edges: ["all"] (default) borders every cell on all sides, ["outline"] only the range perimeter, or any of ["top","bottom","left","right"] applied to every cell. style: thin, medium, thick, double, dashed, dotted, hair.

Set text alignment on a range.

horizontal: left, center, right, justify. vertical: top, center, bottom. text_rotation: degrees 0-180.

Set the number format for a range.

Accepts an alias — general, integer, decimal, currency, percent, date, datetime, time, text, scientific — or any Excel format code like '#,##0.00 "kg"' or '€#,##0.00'.

Set the width of one column ('B') or a span ('B:D'). Width is in Excel character units (default column width is about 8.4).

Set the height of one row ('2') or a span ('2:5'), in points.

Approximate Excel's auto-fit: size each column to its longest value.

columns like 'A:F'; omit to fit every used column. Widths are clamped to the 8-80 range.

Merge a range into one cell. Only the top-left value is kept.

Unmerge a previously merged range (must match the merged area exactly).

Freeze rows above and columns left of the given cell.

'A2' freezes row 1; 'B1' freezes column A; 'B2' freezes both. Omit cell (or pass 'A1') to unfreeze.

Convert a range into a native Excel table with a built-in style.

The first row of the range must be unique, non-empty headers. Styles are Excel's built-ins: TableStyleLight1-21, TableStyleMedium1-28, TableStyleDark1-11.

Add a conditional formatting rule to a range.

rule_type:

• 'color_scale': gradient by value; colors = 2 or 3 hex/named colors (default red-yellow-green).

• 'data_bar': in-cell bars; colors = [bar_color] (default blue).

• 'cell_value': highlight cells matching operator (greaterThan, lessThan, equal, notEqual, between, notBetween, greaterThanOrEqual, lessThanOrEqual) against values (two values for between); uses fill_color/font_color.

• 'formula': highlight where an Excel formula (relative to the range's top-left cell) is TRUE, e.g. 'ISBLANK(A2)'; uses fill_color/font_color.

Apply a common style in one call.

Presets: header (bold white on dark blue, centered), title (large bold), zebra (banded rows, first row skipped), currency, percent, highlight (yellow fill), total_row (bold, double top border).

Inspect a cell's formatting: font, fill, alignment, borders, number format, dimensions, and merge status.

Write an Excel formula to one cell, e.g. 'SUM(B2:B10)' (leading '=' optional).

Formulas are stored, not calculated — Excel evaluates them when the file is next opened. Reading the cell back returns the formula text.

Fill a range with a formula, adjusting relative references like Excel's fill handle.

The formula is written as given to the range's top-left cell and translated for the rest: '=B22' filled into C2:C4 becomes '=B32' in C3 and '=B42' in C4. Use $ to pin references ('=$B$1B2').

Read the formula stored in a cell. formula is null when the cell holds a plain value instead of a formula.

Create a workbook-level named range, e.g. 'SalesData' for 'Sheet1!A1:C10'. The name can then be used in formulas: '=SUM(SalesData)'.

List the workbook's defined names and the ranges they refer to.

Delete a defined name. The cells it referred to are unaffected.

Insert a picture with its top-left corner at the given cell.

Supports png, jpg, gif, bmp. Give width_px and/or height_px to resize; a single dimension scales proportionally. The image file is embedded in the workbook, so the source file is not needed afterwards.

List the pictures embedded in a sheet, with the index used by delete_image.

Delete an embedded picture by its index (see list_images).

Open the workbook in a visible Excel window for the user to see.

Saves the session first so Excel shows the latest edits. Edits the user then makes in Excel do NOT flow back into this session — to continue editing here afterwards, have the user save and close Excel, then close_workbook and open_workbook again to reload.

Export the workbook (or one sheet) to a PDF file via Excel.

Saves the session first. Requires Microsoft Excel on Windows (uv sync --extra com).

Run a VBA macro in the workbook via Excel, then reload the session so changes the macro made are visible to the other tools.

Only .xlsm workbooks can hold macros. macro_name is the procedure name (e.g. 'FormatReport' or 'Module1.FormatReport'); args are passed through. The workbook is saved after the macro runs. Requires Microsoft Excel on Windows (uv sync --extra com), and macros must be trusted for automation.

Protect a sheet so locked cells cannot be edited in Excel.

All cells are locked by default — use set_cell_locked(range, locked=false) BEFORE protecting to keep specific cells editable. The allow_* flags let users still format, sort, or filter while protected. A password (optional) is required to unprotect in Excel; note this is Excel's standard sheet protection, a deterrent rather than encryption.

Remove sheet protection (no password needed here — this edits the file directly, unlike Excel's UI).

Mark cells as locked or unlocked. Takes effect only while the sheet is protected (protect_sheet); all cells start locked, so unlock the cells users should edit, then protect the sheet.

Find cells whose value contains the query text (or matches the regex).

Searches one sheet if given, otherwise the whole workbook. Values are matched against their string form; formulas match on formula text. Returns up to 500 matches with their cell addresses.

Replace text in every matching cell within a range.

Only text (string) cells are modified; numbers, dates, and formulas are left untouched. With regex=True, replace may use groups like \1.

List all sheets in the workbook, in tab order.

Add a new empty sheet. index 0 puts it first; omit to append at the end.

Delete a sheet and all its data. A workbook must keep at least one sheet.

Rename a sheet. Note: formulas referencing the old name are not rewritten.

Duplicate a sheet within the workbook, including values and formatting.

Set which sheet unqualified ranges like 'A1:C10' refer to.

Insert empty rows before the given 1-based row number.

Rows at and below row shift down. Note: formulas are not re-adjusted.

Delete rows starting at the given 1-based row number. Rows below shift up.

Insert empty columns before the given column ('B' or 1-based index).

Columns at and right of it shift right. Note: formulas are not re-adjusted.

Delete columns starting at the given column ('B' or 1-based index).

Import a CSV file into a sheet, starting at start_cell.

With detect_types=true (default), numeric fields become numbers and empty fields become empty cells; otherwise everything is written as text. Existing cells in the target area are overwritten.

Export a range (or a sheet's whole used range) to a CSV file.

Formula cells export their formula text; run recalculate_workbook and read from read_calculated_range if you need computed values instead. Dates become ISO strings, empty cells become empty fields.

Export a range (or a sheet's whole used range) to a JSON file.

With first_row_is_header=true (default) the output is a list of objects keyed by the header row; otherwise a list of row arrays.

Open an existing Excel file (.xlsx or .xlsm) for reading and editing.

Returns a session_id that every other tool requires. Changes are kept in memory until save_workbook is called. Use an absolute file path.

Create a new Excel workbook at the given absolute path.

The file is not written to disk until save_workbook. Fails if the file already exists unless overwrite=True. Returns a session_id for editing.

Write the workbook's in-memory changes to its file on disk.

Save the workbook to a new absolute path; the session then points at that file.

Close a workbook session and free its memory.

Refuses to close if there are unsaved changes, unless discard_changes=True.

List all currently open workbook sessions with their session_ids.

Get workbook details: sheet names plus each sheet's used-range dimensions.