io.github.arose26/xlsx-audit-mcp

xlsx-audit-mcp

An MCP server that audits Excel workbooks. Other Excel MCP servers read and write your data — this one reviews your model:

• "What feeds the Total cell on the Summary sheet?" — precedent tracing
• "If I change this assumption, what breaks?" — dependent tracing, including cells that consume it through ranges like SUM(A1:A40)
• "Audit this workbook" — circular references with example chains, volatile functions (INDIRECT, OFFSET, NOW, RAND...), hardcoded constants buried inside formulas, external workbook links, merged cells, extra-long formulas

Spreadsheet mistakes are famously expensive. This is the "trace precedents" discipline auditors apply by hand, exposed to an LLM for a whole workbook at once. Local files only; nothing leaves your machine.

Quick start

Claude Code

claude mcp add xlsx-audit -- npx -y xlsx-audit-mcp

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "xlsx-audit": {
      "command": "npx",
      "args": ["-y", "xlsx-audit-mcp"]
    }
  }
}

Then: "Audit C:\models\budget-2026.xlsx and tell me what looks fragile."

Tools

Tool	What it does
workbook_overview	Sheets, dimensions, formula counts, defined names, external links
list_formulas	Formulas with addresses and cached values, filterable (INDIRECT, VLOOKUP, ...)
trace_cell	One cell's formula, value, precedents, and dependents (direct + via ranges)
audit_workbook	Ranked risk report across the whole model

How it works

• Reference tokenizer that understands real formulas: string literals are stripped first (the "A1" in INDIRECT("A1") is not a reference), function names can't collide (the G10 in LOG10(...) is not a cell), $ absolutes, quoted sheet names ('My Data'!A1), and ranges are handled.
• Shared formulas are materialized. Excel stores filled formulas once with an offset scheme; the loader translates them per-cell (relative refs shifted, absolutes preserved), so dependency queries see what each cell actually computes.
• Ranges are never expanded for storage — dependents queries use range-containment tests, and cycle detection caps range fan-out (a SUM(A:A) can't explode the graph; capped ranges are reported, not silently dropped).
• No formula evaluation. Cached values from the file are shown instead — no spreadsheet engine dependency.

Known limitations: R1C1 notation and structured table references ([@Column]) are counted but not resolved into the graph.

Development

npm install
npm test                 # offline tests — synthetic workbooks built in-suite
npm run build            # tsc → dist/
node scripts/smoke.mjs   # end-to-end: generates a workbook, drives the server over stdio

Architecture: src/xlsx.ts (zip + XML → workbook model) and src/formulas.ts (tokenizer, graph, smells) are pure logic; src/index.ts is the MCP wiring.

License

MIT