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.

xlsx-tools-mcpexposes 20 Model Context Protocol (MCP) tools that give an LLM agent accurate, structure-preserving readandwrite access to Excel.xlsxfiles. 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 shouldnotdestroy what it doesn't touch.

- 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 formulastringsbut never evaluates them. After every value/formula write the server runs a headless LibreOffice pass to recompute real results, then returnserrors_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—aggregate_sheetgroups and aggregates on top of the normal read path, so merged cells and styling in the source range are preserved before flattening.
- 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.
- XML-bomb protection— thedefusedxmlpackage 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— setXLSX_MCP_FILESto preload one or more workbooks; tools can then be called withpathomitted or with a short alias instead of a full filesystem path.

Live viapypistats.org, non-mirror downloads. These count download events, not unique users or installs — one user can trigger many downloads (CI, reinstalls, Docker rebuilds, mirrors).

┌──────────────────────── Supervisor (MCP transport, stdio) │ src/xlsx_tools_mcp/server.py 20 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 errors

# macOS brew install --cask libreoffice # Debian / Ubuntu sudo apt-get install -y libreoffice-calc

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-mcp

claude mcp add xlsx-tools-mcp -- uvx xlsx-tools-mcp

{ "mcpServers": { "xlsx-tools-mcp": { "command": "uvx", "args": ["xlsx-tools-mcp"] } } }

Inopencode.json(project) or~/.config/opencode/opencode.json(global):

{ "mcp": { "xlsx-tools-mcp": { "type": "local", "command": ["uvx", "xlsx-tools-mcp"], "enabled": true } } }

If you cloned the repo instead of installing from PyPI, point the client at your local checkout by swappinguvx xlsx-tools-mcpfor the dynamicuv runform (use theabsolutepath to the clone):

{ "mcpServers": { "xlsx-tools-mcp": { "command": "uv", "args": ["--directory", "/absolute/path/to/xlsx-reader", "run", "xlsx-tools-mcp"] } } }

{ "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-readerwith the actual location of your clone.

Set theXLSX_MCP_FILESenvironment variable in theMCP server configenvsection (not your interactive shell — the server is launched by the client) to preload workbooks at startup. Format: comma-separatedalias=absolute/pathentries, or bare absolute paths:

XLSX_MCP_FILES=name=/abs/path/to/name.xlsx,report=/data/report.xlsx

Bare paths get an alias defaulting to the filename:

- One file configured→ every tool can be called withpathomitted entirely.
- Multiple files configured→ pass the alias (or filename) aspath.
- list_configured_files()returns the alias → absolute-path mapping.
- Raw absoluteand relativepaths still work for files you didn't preload.

Claude Code —.mcp.jsonwith preloading:

{ "mcpServers": { "xlsx-tools-mcp": { "command": "uvx", "args": ["xlsx-tools-mcp"], "env": { "XLSX_MCP_FILES": "report=/data/report.xlsx,sales=/data/sales.xlsx" } } } }

{ "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 } } }

All 20 tools. Unless noted,pathaccepts a filesystem path, a preloaded alias/filename, or may be omitted when exactly one file is preloaded.create_workbookis the exception — itspathis 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!"}.

{ "sheet": "Sheet1", "cells": [ { "cell": "A1", "value": 100 }, { "cell": "B1", "formula": "=A1*2" } ], "recalculate": true, "path": "/data/budget.xlsx" }

{ "saved": true, "recalculated": true, "errors_found": [], "message": "Recalculated with LibreOffice headless." }

If a formula this touches produced an error,errors_foundwould look like:

{ "saved": true, "recalculated": true, "errors_found": [ { "sheet": "Sheet1", "cell": "C5", "error": "#DIV/0!" } ], "message": "Recalculated with LibreOffice headless." }

- 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.
- 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.

- 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 werenotrecomputed (cached values may be stale). Install LibreOffice (seeRequirements).
- Recalculation is slow or times out— raiseXLSX_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.
- "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.

SeeCONTRIBUTING.md. Run the test suite with:

A specialized Google Sheets integration server that allows the LLM to read, write, and manage spreadsheet data in real-time. This server supports cell-level manipulation, bulk range updates, and full worksheet retrieval, enabling the model to perform data analysis, logging, and automated reporting directly within Google Worksheets.If you have functions which take range value then first read the sheet and decide where user is asking to add data and define range by your own.Provides 46 tools for Gsheet