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 20 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 — `aggregate_sheet` groups 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 `.lock` file (filelock), so writes never interleave and corrupt the file.
• 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; 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     20 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

The server finds LibreOffice by checking `soffice` / `libreoffice` on `PATH` and the standard macOS install location (`/Applications/LibreOffice.app/Contents/MacOS/soffice`).

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

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-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 20 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."
}

Security & concurrency

• 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 `.lock` file (via `filelock`). 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, 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.
• "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