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

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

Write

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

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 raises AccessDeniedError. Case-insensitive path comparisons and multi-drive paths on Windows are supported.
• Auto-backup & restore — Write tools will automatically create a .bak sibling file before modifying the workbook if backup=True (which defaults to XLSX_MCP_AUTO_BACKUP=true). Use XLSX_MCP_BACKUP_DIR to save backups to a specific folder. 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 command execution. Pass allow_external_formulas=True to bypass this check.
• AST safe query validation — query_sheet uses 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 — defusedxml is 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>.lock file (via filelock). 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, default 60) caps how long the LibreOffice recalculation pass may run.
• Lock timeout — XLSX_MCP_LOCK_TIMEOUT (seconds, default 10) caps how long a tool will wait to acquire the per-file lock before failing.

Troubleshooting

• errors_found is empty even though my formula is broken — recalculation likely didn't run. Check the message field: 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, but recalculated will be false and message says the recalc timed out.
• LockTimeoutError on concurrent access — another operation holds the lock. Raise XLSX_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.
• path required / no file configured — you called a tool without path but no (or multiple) files are preloaded. Preload one file via XLSX_MCP_FILES, pass an explicit alias, or pass a raw path.

Development / Contributing

See CONTRIBUTING.md. Run the test suite with:

uv run pytest