xlsx-tools-mcp
An MCP server that gives an LLM agent structure-preserving read and write access to Excel .xlsx workbooks, with optional LibreOffice formula recalculation.
Discover files —
list_configured_fileslists workbooks preloaded viaXLSX_MCP_FILES;pathcan be an alias, omitted if only one file is configured, or a raw filesystem path.Inspect structure —
list_sheets(sheet names with approximate row/column counts) andget_workbook_info(exact dimensions, sheet state, active sheet, defined names).Read data —
read_sheetreturns a 2D array (optionally limited bycell_range/max_rows),get_cellreturns full single-cell detail (value, formula, number format, font, fill, merge, comment).Search —
search_workbookdoes substring matching across one or all sheets, with case sensitivity and a match limit.Aggregate —
aggregate_sheetgroups and aggregates with pandas, e.g. sum an amount column by region.Create workbooks —
create_workbookmakes a new.xlsxwith named sheets, optionally overwriting.Write values/formulas —
write_cellstargets specific cells (values or=formulas),append_rowsadds rows after the last used row; both can create the sheet if missing and both trigger recalculation by default.Manage sheets —
create_sheet(optionally at an index),delete_sheet, andmerge_cells/unmerge_cellsfor merged ranges.Manage rows and columns —
insert_rows,delete_rows,insert_columns,delete_columns(1-based positions, shifting neighbors).Format cells —
set_cell_styleapplies bold, italic, font size/color, background color, alignment, borders, and number formats to a range.Recalculate formulas —
recalculate_workbookforces a headless LibreOffice pass and reports any Excel error values found.Note: the README advertises 29 tools (adding e.g.
rename_sheet,copy_sheet,query_sheet,profile_sheet,autofit_columns,clear_range,create_table,create_chart,restore_backup), but the supplied schema exposes only these 20.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@xlsx-tools-mcp sum the values in column C of the sheet named 'Expenses'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
xlsx-tools-mcp
An MCP server for reading and writing Excel (.xlsx) files with high accuracy, while preserving the file's existing structure, styles, and formulas.
Overview
xlsx-tools-mcp exposes 29 Model Context Protocol (MCP) tools that give an LLM agent accurate, structure-preserving read and write access to Excel .xlsx files. It runs as a standard stdio MCP server: you install it and register it with an MCP client (Claude Code, OpenCode, etc.), and the client's agent can list sheets, read cell ranges, search values, aggregate data, write cells/formulas, manage sheets/rows/columns, apply styles, and force formula recalculation.
It is built around the principle that editing an existing workbook should not destroy what it doesn't touch.
Features
Structure-preserving writes via openpyxl — writes load the existing workbook and save it back, preserving styles, merged cells, comments, and any aspect the edit doesn't touch.
Never-stale formula results via LibreOffice recalculation — openpyxl writes formula strings but never evaluates them. After every value/formula write the server runs a headless LibreOffice pass to recompute real results, then returns
errors_found— any Excel error values (#REF!,#DIV/0!,#N/A, …) produced by the recalculation.Fast reads via python-calamine — a Rust-backed parser for accurate, fast type inference, with an automatic openpyxl fallback when you need formulas/styles/comments or when calamine can't parse the file.
pandas-based grouping/aggregation & querying —
aggregate_sheetandquery_sheetperform operations without destroying source structure, equipped with AST expression validation to block code injection.Native Excel objects — create formal Excel Tables (
create_table) with autofilter and styles, and native charts (create_chartfor bar, line, pie, scatter).Sheet lifecycle & formatting — rename sheets (
rename_sheet), duplicate sheets with styles intact (copy_sheet), clear ranges (clear_range), and auto-fit column widths (autofit_columns).Cross-platform reliability (Windows, macOS, Linux) — case-insensitive path confinement, comma or semicolon
;environment delimiters, safe atomic file replacement with transient lock retry (WinError 32/ antivirus defense), and silent headless recalculation without window flicker.Per-file locking — concurrent tool calls (or other processes) touching the same workbook are serialized via a sibling
<path>.lockfile (filelock), so writes never interleave and corrupt the file.Path confinement —
XLSX_MCP_ALLOWED_DIRS(comma or semicolon-separated) restricts all reads and writes to specific directories. If set, any attempt to access a file outside these boundaries raisesAccessDeniedError. Case-insensitive path comparisons and multi-drive paths on Windows are supported.Auto-backup & restore — Write tools automatically create a
.baksibling file before modifying the workbook ifbackup=True(which defaults toXLSX_MCP_AUTO_BACKUP=true). Userestore_backupto atomically revert changes.Formula injection guard —
write_cellsandappend_rowsreject formulas containingWEBSERVICE,HYPERLINK,INDIRECT,RTD,CALL,REGISTER, or DDE commands (|) by default to prevent data exfiltration or malicious links. Passallow_external_formulas=Trueto bypass this check.XML-bomb protection — the
defusedxmlpackage is an automatic dependency; openpyxl detects it and uses its hardened XML parser, so hostilexlsxXML can't expand into resource exhaustion.Preload files at startup — set
XLSX_MCP_FILESto preload one or more workbooks (comma or semicolon-separated); tools can then be called withpathomitted or with a short alias instead of a full filesystem path.
Related MCP server: mcp-xlsx-server
Download Stats
Live via pypistats.org, non-mirror downloads. These count download events, not unique users or installs — one user can trigger many downloads (CI, reinstalls, Docker rebuilds, mirrors).
Architecture
┌──────────────────────── Supervisor (MCP transport, stdio)
│ src/xlsx_tools_mcp/server.py 29 MCP tools + instructions
│ src/xlsx_tools_mcp/settings.py env vars, preloaded files, path resolution
│ src/xlsx_tools_mcp/locking.py per-file <path>.lock serialization
│ src/xlsx_tools_mcp/errors.py domain error types
│ src/xlsx_tools_mcp/recalc.py LibreOffice headless recalc + error scanning
│
├─ Read path
│ src/xlsx_tools_mcp/io/reader.py calamine primary → openpyxl fallback
│ src/xlsx_tools_mcp/io/transform.py pandas aggregation on read results
│
└─ Write path
src/xlsx_tools_mcp/io/writer.py openpyxl → LibreOffice recalc → scan errorsThe io layer (io/) is deliberately decoupled from the MCP transport (server.py). Each MCP tool is a thin wrapper that resolves the target path, takes the per-file lock, and calls one io-layer function. This keeps the core logic independent of MCP, so it can be tested directly (see tests/).
The recalculation tradeoff
After a write that touches cell values or formulas, the server runs soffice --headless --convert-to xlsx on the file so every formula gets a real computed value. This round-trip recomputes formulas but re-exports the whole workbook — it is a tradeoff, not a guarantee of bit-perfect preservation. Features that openpyxl would otherwise preserve may not survive identically: pivot tables, charts, data validation, some formats, and some defined names.
If you're working on a structurally complex workbook where that risk matters, you can pass recalculate=False on the value/formula-writing tools (write_cells, append_rows, insert_rows, delete_rows, insert_columns, delete_columns) to save with openpyxl only and skip the round-trip entirely.
Requirements
Python ≥ 3.10
LibreOffice — optional but recommended. Needed only for formula recalculation. Without it, writes still succeed (saved via openpyxl) but formulas are not recomputed and a warning is returned in the
messagefield.
Install LibreOffice:
# macOS
brew install --cask libreoffice
# Debian / Ubuntu
sudo apt-get install -y libreoffice-calc
# Windows
winget install TheDocumentFoundation.LibreOfficeThe server finds LibreOffice by checking soffice / libreoffice on PATH, the standard macOS install location (/Applications/LibreOffice.app/Contents/MacOS/soffice), and standard Windows paths (%ProgramFiles%\LibreOffice\program\soffice.exe, etc.). On Windows, headless recalculation runs silently without window flicker (CREATE_NO_WINDOW) and with isolated user profiles.
Installation
The server speaks stdio transport (standard MCP): after installation it waits for an MCP client to connect and call tools. You don't usually run it yourself; you register it with a client.
1. From PyPI via uvx (recommended — no clone)
uvx xlsx-tools-mcpuvx fetches and runs the published package without polluting your project. This is the simplest way to power up an MCP client (see configuration snippets below).
2. From source
git clone https://github.com/ruriazz/xlsx-tools-mcp.git
cd xlsx-tools-mcp
uv sync
# run the server (useful for local dev / debugging):
uv run xlsx-tools-mcp3. Via pip
pip install xlsx-tools-mcpThis installs the console entry point, so you can run the server directly:
xlsx-tools-mcpConfiguration for MCP clients
The simplest registration for every client uses uvx xlsx-tools-mcp (no clone, always the published version).
Tip for Windows: In JSON client configuration files (
.mcp.json,opencode.json), use forward slashes (e.g."C:/path/to/data.xlsx") or escaped backslashes (e.g."C:\\\\path\\\\to\\\\data.xlsx") to prevent JSON escape sequence errors.
Claude Code
claude mcp add xlsx-tools-mcp -- uvx xlsx-tools-mcpOr via .mcp.json in your project:
{
"mcpServers": {
"xlsx-tools-mcp": { "command": "uvx", "args": ["xlsx-tools-mcp"] }
}
}OpenCode
In opencode.json (project) or ~/.config/opencode/opencode.json (global):
{
"mcp": {
"xlsx-tools-mcp": { "type": "local", "command": ["uvx", "xlsx-tools-mcp"], "enabled": true }
}
}When running from a source clone
If you cloned the repo instead of installing from PyPI, point the client at your local checkout by swapping uvx xlsx-tools-mcp for the dynamic uv run form (use the absolute path to the clone):
Claude Code .mcp.json:
{
"mcpServers": {
"xlsx-tools-mcp": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/xlsx-reader", "run", "xlsx-tools-mcp"]
}
}
}OpenCode:
{
"mcp": {
"xlsx-tools-mcp": {
"type": "local",
"command": ["uv", "--directory", "/absolute/path/to/xlsx-reader", "run", "xlsx-tools-mcp"],
"enabled": true
}
}
}Replace /absolute/path/to/xlsx-reader with the actual location of your clone.
Preloading files (XLSX_MCP_FILES)
Set the XLSX_MCP_FILES environment variable in the MCP server config env section (not your interactive shell — the server is launched by the client) to preload workbooks at startup. Format: comma- or semicolon-separated alias=absolute/path entries, or bare absolute paths:
XLSX_MCP_FILES=name=/abs/path/to/name.xlsx,report=/data/report.xlsxBare paths get an alias defaulting to the filename:
XLSX_MCP_FILES=/abs/path/to/sales.xlsxWith alias/filename as the alias:
One file configured → every tool can be called with
pathomitted entirely.Multiple files configured → pass the alias (or filename) as
path.list_configured_files()returns the alias → absolute-path mapping.Raw absolute and relative paths still work for files you didn't preload.
Claude Code — .mcp.json with preloading:
{
"mcpServers": {
"xlsx-tools-mcp": {
"command": "uvx",
"args": ["xlsx-tools-mcp"],
"env": {
"XLSX_MCP_FILES": "report=/data/report.xlsx,sales=/data/sales.xlsx"
}
}
}
}OpenCode with preloading:
{
"mcp": {
"xlsx-tools-mcp": {
"type": "local",
"command": ["uvx", "xlsx-tools-mcp"],
"env": { "XLSX_MCP_FILES": "report=/data/report.xlsx,sales=/data/sales.xlsx" },
"enabled": true
}
}
}Tool reference
All 29 tools. Unless noted, path accepts a filesystem path, a preloaded alias/filename, or may be omitted when exactly one file is preloaded. create_workbook is the exception — its path is required because a new file is never preloaded.
Response shape (all write tools): every write tool returns
{"saved": bool, "recalculated": bool, "errors_found": list, "message": str}. When non-empty,errors_foundis a list of{"sheet": "...", "cell": "B2", "error": "#DIV/0!"}.
Inspect / Read
Tool | Description |
| List files preloaded at startup via |
| List every sheet in the workbook with approximate row/column counts (calamine). |
| Workbook-level metadata: per-sheet exact dimensions, |
| Read cell values. |
| Full detail for a single cell: value (cached computed), formula, number format, font (bold/italic/size/color), fill color, merge state, comment. |
| Substring search across one or all sheets. |
| Group and aggregate with pandas. |
| Profile sheet metadata: inferred types, null counts, min/max, sample values. |
| Filter sheet data using pandas expressions with AST-hardened code injection defense. |
Write
Tool | Description |
| Create a new |
| Write values and/or formulas into specific cells. |
| Append rows after the last used row. |
| Add a new empty sheet. |
| Delete a sheet. Fails if it's the only sheet left. |
| Rename an existing sheet. |
| Duplicate a sheet including its contents, formulas, and styles. |
| Insert blank rows before |
| Delete rows starting at |
| Insert blank columns before |
| Delete columns starting at |
| Merge a rectangular range (e.g. |
| Undo a merge on a previously-merged range. |
| Apply formatting to a range (e.g. |
| Automatically adjust column widths based on maximum text length to prevent clipping. |
| Clear cell values and/or styles within a specified range without deleting rows or columns. |
| Create a formal Excel Table over a range. |
| Add a native Excel chart (bar, line, pie, scatter). |
| Force a LibreOffice headless recalculation pass and report any formula errors found. |
| Restore a |
Example payload — write_cells
A call writing a formula and a value:
{
"sheet": "Sheet1",
"cells": [
{ "cell": "A1", "value": 100 },
{ "cell": "B1", "formula": "=A1*2" }
],
"recalculate": true,
"path": "/data/budget.xlsx"
}Matching response:
{
"saved": true,
"recalculated": true,
"errors_found": [],
"message": "Recalculated with LibreOffice headless."
}If a formula this touches produced an error, errors_found would look like:
{
"saved": true,
"recalculated": true,
"errors_found": [
{ "sheet": "Sheet1", "cell": "C5", "error": "#DIV/0!" }
],
"message": "Recalculated with LibreOffice headless."
}Example payload — query_sheet
{
"sheet": "Sales",
"filter_query": "Revenue > 500 and Status == 'PAID'",
"columns": ["Customer", "Revenue"],
"max_rows": 10
}Example payload — create_table & create_chart
{
"sheet": "Summary",
"cell_range": "A1:D10",
"table_name": "SalesTable",
"style_name": "TableStyleMedium9"
}{
"sheet": "Summary",
"chart_type": "bar",
"data_range": "B1:B10",
"categories_range": "A2:A10",
"title": "Monthly Revenue",
"target_cell": "F2"
}Environment variables
Variable | Default | Description |
| empty | Comma or semicolon-separated |
| empty | Comma or semicolon-separated directories to confine file access (paths outside raise |
|
| Automatically create a |
| empty | Custom directory for backup files (defaults to beside the target file). |
|
| Timeout in seconds for headless LibreOffice formula recalculation. |
|
| Timeout in seconds to acquire per-file lock before failing. |
Security & concurrency
Path confinement —
XLSX_MCP_ALLOWED_DIRS(comma or semicolon-separated) restricts all reads and writes to specific directories. If set, any attempt to access a file outside these boundaries raisesAccessDeniedError. Case-insensitive path comparisons and multi-drive paths on Windows are supported.Auto-backup & restore — Write tools will automatically create a
.baksibling file before modifying the workbook ifbackup=True(which defaults toXLSX_MCP_AUTO_BACKUP=true). UseXLSX_MCP_BACKUP_DIRto save backups to a specific folder. Userestore_backupto atomically revert changes.Formula injection guard —
write_cellsandappend_rowsreject formulas containingWEBSERVICE,HYPERLINK,INDIRECT,RTD,CALL,REGISTER, or DDE commands (|) by default to prevent data exfiltration or command execution. Passallow_external_formulas=Trueto bypass this check.AST safe query validation —
query_sheetuses an AST parser to strictly allow only comparisons, boolean logic, and safe operators, blocking@variable lookups, code execution calls, and private dunder attributes.XML-bomb protection —
defusedxmlis an automatic dependency of this package. openpyxl auto-detects it and uses its hardened XML parser, so a malicious.xlsx(a zip of XML) can't trigger entity-expansion resource exhaustion. No configuration needed.Per-file locking — every read/write acquires a sibling
<path>.lockfile (viafilelock). Concurrent tool calls or other processes touching the same workbook are serialized so writes never interleave and corrupt the file.Transient lock resilience — on Windows NTFS, atomic file swaps can momentarily encounter sharing violations (
WinError 32/33) while antivirus scanners or search indexers inspect newly saved files. The server performs an exponential backoff retry to transparently succeed once released, or provides a clear guidance message if the file is permanently open in Microsoft Excel.Recalc timeout —
XLSX_MCP_RECALC_TIMEOUT(seconds, default60) caps how long the LibreOffice recalculation pass may run.Lock timeout —
XLSX_MCP_LOCK_TIMEOUT(seconds, default10) caps how long a tool will wait to acquire the per-file lock before failing.
Troubleshooting
errors_foundis empty even though my formula is broken — recalculation likely didn't run. Check themessagefield: if it says LibreOffice wasn't found, the file was saved via openpyxl as-is and formulas were not recomputed (cached values may be stale). Install LibreOffice (see Requirements).Recalculation is slow or times out — raise
XLSX_MCP_RECALC_TIMEOUT(default 60s). On timeout, the file is still saved, butrecalculatedwill befalseandmessagesays the recalc timed out.LockTimeoutErroron concurrent access — another operation holds the lock. RaiseXLSX_MCP_LOCK_TIMEOUT(default 10s), or retry when the other operation finishes.Workbook is locked by another process/WinError 32— on Windows, Microsoft Excel and some applications lock open files exclusively. Close the workbook in Excel and retry. Transient locks from antivirus scanners or search indexers are automatically retried by the server before failing."Sheet not found" — the error message lists the available sheet names, so you can pick the correct one.
pathrequired / no file configured — you called a tool withoutpathbut no (or multiple) files are preloaded. Preload one file viaXLSX_MCP_FILES, pass an explicit alias, or pass a raw path.
Development / Contributing
See CONTRIBUTING.md. Run the test suite with:
uv run pytestAvailable Tools
29 toolsaggregate_sheetA
Group and aggregate sheet data with pandas (e.g. sum sales by region).
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. group_by: Column names to group by (taken from the header row). agg: Mapping of column name to aggregation function, e.g. {"amount": "sum"}. cell_range: Optional A1-style range to read before aggregating. has_header: Whether the first row of the range holds column names.
Inputs: agg (required), sheet (required), group_by (required), path, +2 more. Returns: object
append_rowsA
Append rows after the last used row of a sheet, then recalculate the workbook.
Set recalculate=False to skip the LibreOffice recompute (e.g. for structurally
complex workbooks you don't want round-tripped).
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. rows: List of rows, each a list of cell values in column order. create_sheet_if_missing: Create the sheet first if it doesn't exist yet. recalculate: Run the LibreOffice recompute pass after saving.
Inputs: rows (required), sheet (required), path, backup, +3 more. Returns: object
autofit_columnsC
Automatically adjust column widths based on maximum text length.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. min_width: Minimum allowed column width. max_width: Maximum allowed column width. padding: Extra padding characters to add to max length.
Inputs: sheet (required), path, backup, padding, +2 more. Returns: object
clear_rangeA
Clear cell values and/or styles within a specified range without deleting rows or columns.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. cell_range: A1-style range (e.g. "A1:D10") to clear. clear_values: Whether to clear cell values (True by default). clear_styles: Whether to clear cell styles/formats (False by default).
Inputs: sheet (required), cell_range (required), path, backup, +2 more. Returns: object
copy_sheetA
Duplicate a sheet including its contents, formulas, and styles.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. source_sheet: Name of the sheet to duplicate. target_sheet: Name of the new sheet (1-31 chars, valid Excel sheet name).
Inputs: source_sheet (required), target_sheet (required), path, backup. Returns: object
create_chartA
Create a native Excel chart (bar, line, pie, scatter).
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. chart_type: One of "bar", "line", "pie", "scatter". data_range: A1-style range holding the chart series values (e.g. "B1:B10"). categories_range: Optional A1-style range holding series category labels (e.g. "A2:A10"). title: Title string displayed on the chart. target_cell: Cell coordinate where the top-left corner of the chart is placed. backup: Whether to create a backup before modifying the workbook.
Inputs: sheet (required), chart_type (required), data_range (required), path, +4 more. Returns: object
create_sheetB
Add a new empty sheet to an existing workbook.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Name for the new sheet. index: Zero-based position to insert at; omit to append at the end.
Inputs: sheet (required), path, index, backup. Returns: object
create_tableA
Create a formal Excel Table (ListObject) on the specified range.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. cell_range: A1-style range (e.g. "A1:D10"). table_name: Unique table identifier across the workbook. style_name: Table style name (e.g. "TableStyleMedium9"). show_filter: Whether to display auto-filter dropdown arrows. show_row_stripes: Whether to apply alternating row shading. backup: Whether to create a backup before modifying the workbook.
Inputs: sheet (required), cell_range (required), table_name (required), path, +4 more. Returns: object
create_workbookA
Create a new .xlsx workbook.
Args: path: Path for the new file. New files aren't preloaded, so this must be a real path. sheets: Sheet names to create (defaults to a single "Sheet1"). overwrite: Replace an existing file at path when True.
Inputs: path (required), sheets, overwrite. Returns: object
delete_columnsA
Delete columns, shifting the columns to their right leftward.
Set recalculate=False to skip the LibreOffice recompute (e.g. for structurally
complex workbooks you don't want round-tripped).
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. start_column: 1-based column index to start deleting from. count: Number of columns to delete. recalculate: Run the LibreOffice recompute pass after saving.
Inputs: sheet (required), start_column (required), path, count, +2 more. Returns: object
delete_rowsA
Delete rows, shifting the rows below them upward.
Set recalculate=False to skip the LibreOffice recompute (e.g. for structurally
complex workbooks you don't want round-tripped).
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. start_row: 1-based row index to start deleting from. count: Number of rows to delete. recalculate: Run the LibreOffice recompute pass after saving.
Inputs: sheet (required), start_row (required), path, count, +2 more. Returns: object
delete_sheetA
Delete a sheet from a workbook. Fails if it is the only sheet left.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name to delete.
Inputs: sheet (required), path, backup. Returns: object
get_cellA
Get full detail for a single cell: value, formula, number format, font, fill, merge, comment.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. cell: Cell reference, e.g. "C5".
Inputs: cell (required), sheet (required), path. Returns: object
get_workbook_infoA
Get workbook-level metadata: sheets, exact dimensions, active sheet, defined names.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured.
Inputs: path. Returns: object
insert_columnsA
Insert blank columns, shifting existing columns right.
Set recalculate=False to skip the LibreOffice recompute (e.g. for structurally
complex workbooks you don't want round-tripped).
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. start_column: 1-based column index to insert before. count: Number of columns to insert. recalculate: Run the LibreOffice recompute pass after saving.
Inputs: sheet (required), start_column (required), path, count, +2 more. Returns: object
insert_rowsA
Insert blank rows, shifting existing rows down.
Set recalculate=False to skip the LibreOffice recompute (e.g. for structurally
complex workbooks you don't want round-tripped).
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. start_row: 1-based row index to insert before. count: Number of rows to insert. recalculate: Run the LibreOffice recompute pass after saving.
Inputs: sheet (required), start_row (required), path, count, +2 more. Returns: object
list_configured_filesA
List files preloaded at server startup (via the XLSX_MCP_FILES env var).
Call this first if unsure which files are available — every other tool's path
argument accepts these names directly (or can be omitted if only one is configured),
no filesystem search needed.
Inputs: no named parameters. Returns: object
list_sheetsA
List every sheet in a workbook with its approximate row/column counts.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured.
Inputs: path. Returns: result
merge_cellsC
Merge a rectangular range of cells into one.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. cell_range: A1-style range, e.g. "A1:C1".
Inputs: sheet (required), cell_range (required), path, backup. Returns: object
profile_sheetC
Profile sheet data: metadata, inferred types, null counts, min/max, sample values.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. sample_rows: Number of non-null sample values to return per column.
Inputs: sheet (required), path, sample_rows. Returns: object
query_sheetA
Query sheet data using pandas expressions without returning the entire sheet into the LLM context.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. filter_query: Pandas query expression (e.g. "status == 'PAID' and amount > 500"). columns: Optional list of columns to return. max_rows: Maximum rows to return (default 100). cell_range: Optional range to restrict reading before querying.
Inputs: sheet (required), filter_query (required), path, columns, +2 more. Returns: object
read_sheetA
Read cell values from a sheet.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. cell_range: Optional A1-style range (e.g. "B2:F20"). Omit to read the full used area. max_rows: Optional cap on the number of rows returned, to bound response size for large sheets. offset_row: Skip a number of data rows (0-indexed from first data row). format: "array" (default 2D list), "records" (list of dicts, first row as keys), or "markdown" (table string).
Inputs: sheet (required), path, format, max_rows, +2 more. Returns: object
recalculate_workbookA
Force a LibreOffice headless recalculation pass and report any formula errors found.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured.
Inputs: path. Returns: object
rename_sheetB
Rename an existing sheet.
Warning: This tool does NOT automatically update formula references in other sheets. Formulas depending on the old sheet name will break.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. old_name: Current name of the sheet. new_name: New name for the sheet (1-31 chars, valid Excel sheet name).
Inputs: new_name (required), old_name (required), path, backup. Returns: object
restore_backupA
Restore a backup file over a target workbook atomically.
Args: backup_path: Path to the .bak file to restore from. target_path: Path to the target .xlsx/.xlsm file to overwrite.
Inputs: backup_path (required), target_path (required). Returns: object
search_workbookA
Search cell values across one or all sheets for a substring match.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. query: Substring to search for. sheet: Restrict the search to one sheet; omit to search every sheet. match_case: Case-sensitive match when True. limit: Optional cap on the number of matches returned, to bound response size for large sheets.
Inputs: query (required), path, limit, sheet, +1 more. Returns: result
set_cell_styleB
Apply formatting to a range of cells.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. cell_range: A1-style range, e.g. "A1:D1". style: Keys among: bold, italic, font_size, font_color (hex RGB, e.g. "FF0000"), bg_color (hex RGB), horizontal, vertical (alignment), border ("thin", "medium", "thick", ...), number_format (e.g. "#,##0.00").
Inputs: sheet (required), style (required), cell_range (required), path, +1 more. Returns: object
unmerge_cellsB
Undo a merge on a range of cells.
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. cell_range: A1-style range that was previously merged.
Inputs: sheet (required), cell_range (required), path, backup. Returns: object
write_cellsA
Write values and/or formulas into specific cells, then recalculate the workbook.
Set recalculate=False to skip the LibreOffice recompute (e.g. for structurally
complex workbooks you don't want round-tripped).
Args: path: Path to the .xlsx file, or the name of a preloaded file. Omit if only one file is configured. sheet: Sheet name. cells: List of {"cell": "A1", "value": ...} or {"cell": "B1", "formula": "=A1*2"}. create_sheet_if_missing: Create the sheet first if it doesn't exist yet. recalculate: Run the LibreOffice recompute pass after saving.
Returns:
Write result including errors_found — any Excel error values produced by recalculation.
Inputs: cells (required), sheet (required), path, backup, +3 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Most tools have clearly distinct purposes (row/column edits, merges, styling, charts). Minor overlap exists between read_sheet, profile_sheet, query_sheet, and aggregate_sheet, and between write_cells and append_rows, but the descriptions draw usable boundaries.
All 29 tools follow a consistent verb_noun snake_case convention (get_cell, create_sheet, delete_rows, merge_cells, set_cell_style). No camelCase mixing or vague verbs appear.
At 29 tools the surface is heavy, and a few (read_sheet/profile_sheet/query_sheet) could be consolidated. Still, spreadsheets are a broad domain and most tools map to genuinely distinct operations rather than padding.
The set covers a full lifecycle: file discovery, workbook/sheet CRUD, cell read/write, row/column structural edits, styling, merges, tables, charts, search, aggregation, recalculation, and backup/restore. Very few gaps remain for a spreadsheet tool surface.
Maintenance
Related MCP Connectors
The Excel engine for AI agents: read, check and edit Excel models over MCP.
Document conversion MCP server: PDF to Markdown, image OCR, spreadsheet parsing.
Excel analytics: inspect, query (JSON rows), charts, and JSON-to-xlsx workbook writing.
Token-free MCP server for structured RevoGrid Core, Pro, and Enterprise knowledge retrieval.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for reading and writing .xls (Excel 97-2003) files, enabling data manipulation, sheet listing, and metadata retrieval.MIT
- AlicenseAqualityDmaintenanceMCP server for reading and writing Excel (xlsx) files using SheetJS, providing tools to list sheets, read data, create files, add sheets, and update cells.511 npmMIT
- AlicenseNot gradedqualityBmaintenanceMCP server for Excel-compatible formula evaluation and workbook operations, enabling agents to open, inspect, mutate, recalculate, and save .xlsx files in-memory over stdio.99 npmApache 2.0
- AlicenseAqualityCmaintenanceMCP server for reading and inspecting local Excel files (.xlsx, .xlsm, .xls, .xlsb, .ods) with tools for inspecting metadata, reading ranges, and profiling structure.36 npmMIT