xlsx-tools-mcp

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_sheet and query_sheet perform 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_chart for 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 .lock file (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 raises AccessDeniedError. Case-insensitive path comparisons and multi-drive paths on Windows are supported.
• Auto-backup & restore — Write tools automatically create a .bak sibling file before modifying the workbook if backup=True (which defaults to XLSX_MCP_AUTO_BACKUP=true). Use restore_backup to atomically revert changes.
• Formula injection guard — write_cells and append_rows reject formulas containing WEBSERVICE, HYPERLINK, INDIRECT, RTD, CALL, REGISTER, or DDE commands (|) by default to prevent data exfiltration or malicious links. Pass allow_external_formulas=True to bypass this check.
• XML-bomb protection — the defusedxml package is an automatic dependency; openpyxl detects it and uses its hardened XML parser, so hostile xlsx XML can't expand into resource exhaustion.
• Preload files at startup — set XLSX_MCP_FILES to preload one or more workbooks (comma or semicolon-separated); tools can then be called with path omitted or with a short alias instead of a full filesystem path.

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

The 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 message field.

Install LibreOffice:

# macOS

brew install --cask libreoffice

Debian / Ubuntu

sudo apt-get install -y libreoffice-calc

Windows

winget install TheDocumentFoundation.LibreOffice

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

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

3. Via pip

pip install xlsx-tools-mcp

This installs the console entry point, so you can run the server directly:

xlsx-tools-mcp

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

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

Bare paths get an alias defaulting to the filename:

XLSX_MCP_FILES=/abs/path/to/sales.xlsx

With alias/filename as the alias:

• One file configured → every tool can be called with path omitted 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_found is a list of {"sheet": "...", "cell": "B2", "error": "#DIV/0!"}.

Inspect / Read

| list_configured_files() | List files preloaded at startup via XLSX_MCP_FILES, as an alias → absolute-pa