xlsx-for-ai

Short name: xfa — a real CLI command (xfa <file>, xfa samples, xfa --version) and the prompt shorthand (e.g. "use xfa to read this file"). Same entrypoint as xlsx-for-ai; matches the internal xfa_* / XFA_* brand surface.

Verified values, preserved structure, up to 100MB

The missing reliability layer for spreadsheet work in LLM agents. Read, write, diff, validate, and analyze .xlsx files end-to-end — with merged cells, formulas, named ranges, conditional formatting, pivots, and charts preserved.

xlsx-for-ai makes Claude reliable on real-world Excel files. Forty-plus tools cover the structural surface that pandas-style sandboxes drop on the floor: merged cells, named ranges, formulas with results, conditional formatting, pivots, slicers, charts, comments, data validations, hyperlinks, cross-sheet topology, external links, form controls, VBA macros, document properties, and protection settings. Cross-engine validation catches the corruption other readers silently mask. A hosted recalc engine computes served values in-house — no third-party formula engine in the serve path.

npm install -g xlsx-for-ai

The global install puts the xlsx-for-ai-mcp binary on your PATH — that's what the canonical configs below point at. A pinned global install launches fast and works offline; upgrade with npm install -g xlsx-for-ai@latest when a new version ships.

Upgrading from 1.5.x? This is a re-architecture, not a feature bump: the heavy local engine is gone from the npm package. All rendering happens server-side. The cursor-reads-xlsx alias still works. See Migration below.

---

MCP configuration

Add the server to your agent runtime under the name xfa (so "use xfa to read this" resolves). First invocation auto-registers an anonymous client UUID — no email, no signup, no friction.

Claude Code

The global install auto-registers the xfa MCP server in ~/.claude.json — no extra step:

npm install -g xlsx-for-ai

If your environment skips install scripts (--ignore-scripts, CI, or a sudo install), register it manually:

claude mcp add xfa -- xlsx-for-ai-mcp

Verify: in a new Claude Code session, ask "what MCP tools do you have?" — 52 xlsx_* tools should appear, including xlsx_doctor (one-call health report — try it first on any unknown workbook).

Then run xfa samples (shorthand for xlsx-for-ai samples) to drop two demo workbooks in your working directory and get paste-ready prompts to try.

Cursor

Config file: ~/.cursor/mcp.json

{
  "mcpServers": {
    "xfa": {
      "command": "xlsx-for-ai-mcp"
    }
  }
}

Verify: open Cursor settings → MCP → confirm xfa shows 52 xlsx_* tools.

Continue

Config file: ~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "xfa",
      "command": "xlsx-for-ai-mcp"
    }
  ]
}

Verify: restart VS Code, open the Continue panel, and check the MCP server list.

Codex CLI

Pass --mcp-server on the command line, or add to your Codex config:

{
  "mcpServers": {
    "xfa": {
      "command": "xlsx-for-ai-mcp"
    }
  }
}

Verify: run codex --list-tools and confirm 52 xlsx_* tools are listed.

Zed

Config file: ~/.config/zed/settings.json

{
  "context_servers": {
    "xfa": {
      "command": {
        "path": "xlsx-for-ai-mcp"
      }
    }
  }
}

Verify: open Zed's assistant panel — the xlsx tools should appear in the tool picker.

Windsurf

Config file: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "xfa": {
      "command": "xlsx-for-ai-mcp"
    }
  }
}

Verify: open Windsurf → Cascade → settings, confirm xfa is listed as an active MCP server.

Custom agents / API

For custom MCP clients, the binary is xlsx-for-ai-mcp (stdio transport). Override the API base URL with the XLSX_FOR_AI_API env var for local dev against http://localhost:3000.

Using the raw HTTP API

The MCP client is the easy path, but every tool is also a plain HTTP endpoint you can call from any language — no SDK required. Registration is anonymous and keyless: POST https://api.xlsx-for-ai.dev/api/v1/clients (no auth) returns { client_id, api_key }, then call any tool with Authorization: Bearer <api_key>. The free tier is 10,000 calls/month, 10 MB per file — no billing, no email, no signup.

# Self-issue a key (no signup), then convert report.xlsx to Markdown.
# Needs jq, and bash or zsh. The base64 body is passed to curl through a
# process-substitution fd and the token through a --config heredoc on stdin, which
# keeps both out of the argument list. -fsS --max-time makes curl fail loudly on an
# HTTP error or a hang; the guard line stops on a failed key issuance.
KEY=$(curl -fsS --max-time 30 -XPOST https://api.xlsx-for-ai.dev/api/v1/clients \
  -H 'Content-Type: application/json' \
  -d '{"client_version":"2.0.0","platform":"cli"}' | jq -r .api_key)
[ -n "$KEY" ] && [ "$KEY" != null ] || { echo "key issuance failed"; exit 1; }

curl -fsS --max-time 120 -XPOST https://api.xlsx-for-ai.dev/api/v1/tools/xlsx_convert \
  --data-binary @<(base64 < report.xlsx | tr -d '\n' | jq -Rs '{file_b64: ., to: "md"}') \
  -H 'Content-Type: application/json' \
  --config - <<CFG
header = "Authorization: Bearer $KEY"
CFG

The free tier caps files at 10 MB; larger workbooks and higher volume come back as a typed JSON error with an upgrade field (see below).

Beyond the free tier, rate-limited and oversize requests come back as a typed JSON error ({ "error": { "code", "message" } }) carrying an upgrade field with your options — see GET /api/v1/reference for the full contract.

The same governed contract is served read-only from two routes — discover the whole API without a key:

• GET /api/v1/reference — a self-contained human HTML reference for all 52 public-stable tools, including the on-ramp above.
• GET /api/v1/openapi.json — the versioned OpenAPI 3.1 contract, verbatim. Point codegen, Postman, or Scalar/Redoc at it.

---

What it does

52 tools registered in tools/list. Descriptions are intentionally rich — an agent reading a transcript can tell what each tool does and when to reach for it, without extra docs.

Triage / orient

Tool	What it does
xlsx_doctor	One-call workbook health report. HIGH/MEDIUM/LOW findings (macros, external links, hidden sheets, missing metadata, large images) + quick facts + feature flags. The first call to make on an unknown workbook.
xlsx_topology	One-call workbook orientation: sheets × dimensions × formulas × named ranges × tables × validations × hyperlinks × merges in one shot.
xlsx_list_sheets	List all sheet names and metadata. Fast first-call before reading.
xlsx_schema	Infer column types, nullable flags, header row, and sample values per sheet.
xlsx_describe	Pandas-style .describe() on every numeric column — count, mean, std, min, max, quartiles.
xlsx_workbook_views	UI state — frozen panes, zoom, active cell, hidden / veryHidden sheets, tab colors, active tab.
xlsx_properties	Workbook metadata — creator, modified, company, title, custom doc properties.

Read / write

Tool	What it does
xlsx_read	Read a workbook — text, JSON, or markdown. Formulas, named ranges, layout, and data types preserved. Also reads a live Google Sheet by id (source:"gsheets"), read-only, with a read-only Google OAuth token you supply.
xlsx_read_handle	Read by server-side handle instead of bytes — for session flows where the workbook has already been uploaded and shouldn't be transferred again.
xlsx_write	Create or update a workbook from a structured spec. Multi-sheet, formulas, named ranges, table definitions.
xlsx_data_clean	Normalize messy data in place — trim whitespace, coerce types, dedupe rows, fix obvious encoding artifacts. Returns a cleaned copy + a change log. Save-As shape; never mutates the input.
xlsx_diff	Semantic diff between two workbooks — cell-level deltas, formula changes, structural shifts. Deterministic output.
xlsx_redact	Redact PII from a workbook before sharing. Server-side detection; returns redacted copy plus audit manifest.
xlsx_convert	25+ in / 16 out formats (csv, tsv, html, ods, xls, xlsb, dif, sylk, prn, txt, dbf, eth, json, markdown, xlsx, etc.).
xlsx_validate	Cross-engine consistency check — runs the workbook through TWO independent renderers and reports cell-level divergences.
xlsx_session_set_validations	Configure per-session validation rules the server will apply to subsequent calls in the same session (e.g., reject rows missing required columns). Stateful — affects this session only.

Pandas-parity (compute fresh aggregates)

Tool	What it does
xlsx_filter	Filter rows by predicate (column op value). Returns matched rows with optional projection.
xlsx_aggregate	Group-by + aggregate (sum / count / mean / min / max / median / std).
xlsx_sort	Multi-column sort with ascending / descending per column.
xlsx_value_counts	Frequency table for a column (pandas .value_counts()).
xlsx_pivot	Compute a fresh pivot table from raw data — pandas pivot_table() shape.
xlsx_eval	Evaluate freeform formulas or recompute cell refs with our own recalc engine — no third-party formula engine. A formula using a function we haven't implemented yet returns an honest "not supported yet" error, never a wrong value.

Structure-preservation — the moat (pandas drops every one of these on read)

Tool	What it does
xlsx_named_ranges	List every named range with scope, ref, and value preview.
xlsx_tables	List Excel ListObjects (Tables) with column headers, data range, totals row.
xlsx_formulas	Dump every formula across the workbook (cell, sheet, formula text, cached value).
xlsx_data_validations	List cell-level validation rules (dropdowns, numeric/date bounds, text-length, custom).
xlsx_hyperlinks	List hyperlinks with kind classifier (external / internal / mailto / unknown).
xlsx_conditional_formats	List CF rules (color scales, data bars, icon sets, formula-based highlights, top-N, duplicates).
xlsx_styles	Number formats + fonts + fills + alignment, rolled up per sheet or detailed per cell.
xlsx_comments	Both legacy notes AND threaded conversations (multi-author, with display-name resolution).
xlsx_protection	Sheet locks + per-cell locked/hidden flags + workbook structure/window locks.
xlsx_merged_cells	Layout-aware merge listing with master values + kind heuristic (header / horizontal / vertical / block).
xlsx_charts	Chart spec (type, title, series formula refs, axis titles) — ExcelJS doesn't expose these at all.
xlsx_images	Embedded image inventory (format, size, sheet, anchor cells).
xlsx_pivot_tables	Pre-existing pivot definitions — location, source, row/col/page/data fields with agg functions.
xlsx_slicers_timelines	Modern Excel filter UI — slicers (table/pivot bound) + timelines (date-range with selection).
xlsx_external_links	Workbook-to-workbook references with target classification + warning when paths break on share.
xlsx_print_settings	"What would Excel print?" — print area, paper size, margins, headers/footers, print titles.
xlsx_form_controls	Interactive widgets — checkboxes, buttons, drop-downs, spinners, scroll bars, list boxes — with linked cell + bounds.
xlsx_macros	VBA macro presence + module-name heuristics + safety advice (does NOT extract source by policy).

Integrations

Tool	What it does
xlsx_post_slack	Post a workbook to a Slack channel as a file attachment with an optional message. BYOA — the agent supplies the user's Slack bot token (xoxb-…); the token is forwarded to Slack and never persisted. Uses Slack's external upload flow.
xlsx_post_teams	Post a workbook to a Microsoft Teams channel as a file attachment in a channel message, with an optional message. BYOA — the agent supplies the user's Microsoft Graph access token (JWT); the token is forwarded to Microsoft and never persisted. Uses Graph's filesFolder + upload-session + post-message flow.

Integrity verification

Tool	What it does
xlsx_stamp	Sign a workbook with a cryptographic "integrity verification" stamp — Ed25519-signed claims (named factual checks + their pass/fail/skip status + a content hash) embedded in docProps/custom.xml. The stamp travels with the file across saves; a recipient can verify it later to confirm the file hasn't been tampered with since signing. Factual attestations only — never an opinion-shaped seal of approval.
xlsx_verify_stamp	Verify a workbook's embedded stamp. Returns (a) whether the Ed25519 signature is valid against the registered public key, (b) whether the workbook bytes match the hash IN the signed claims, and (c) the full check-result content of the stamp. Three distinct trust signals — signature integrity, content integrity, and what was originally attested.
xlsx_receipt	Attach an AI-generation receipt — Ed25519-signed claims describing the caller-declared agent identity (name, display name, identity URL), generation timestamp, content hash, optional source-file hashes, optional prompt hash, optional MCP tools called, and an optional description. Honesty boundary (load-bearing): the server signs the caller-declared agent.name — it does NOT verify the caller actually IS that agent. Cryptographic identity binding (per-agent issued signing keys) is v1.1+ scope.
xlsx_verify_receipt	Verify a workbook's embedded receipt. Returns the same three trust signals as xlsx_verify_stamp plus the caller-declared agent identity AS declared (no UI affordances implying cryptographic identity verification). Use to surface "where did this file come from?" — backed by the server's signature over caller honest declaration.

Healer — external-reference breakage

Workbooks rot. A file moves and #REF! propagates through every dependent formula. A Power Query connection embeds credentials nobody can rotate. A defined name points at an external workbook that doesn't exist anymore. The healer family diagnoses these classes and applies targeted cures — read-only diagnosis, simulated-before-applied repair, and a high-level intent path when the agent doesn't want to spell out individual cure operations.

Tool	What it does
xlsx_healer_diagnose	Structured report of external-reference breakage — broken external refs, defined-name external refs, Power Query connections with embedded credentials, #REF! propagation maps, multi-hop chains. Read-only.
xlsx_healer_simulate	Show what a specific cure operation would change before applying it — same shape as xlsx_healer_cure but read-only. Use to preview impact when the agent is uncertain whether to proceed.
xlsx_healer_cure	Apply ONE specific cure operation (e.g., strip broken external refs, harmonize a defined name, replace #REF! propagation with a deterministic value). Save-As shape; the source workbook is preserved unless confirm:true is set with mode:"in_place".
xlsx_healer_intent	High-level intent path — make-it-work, make-standalone, migrate — translated into the right sequence of cure ops. For when the agent knows the goal but not the operation.

Tool responses include a citation footer and a _meta block (tool name, version, tier, request ID, powered_by). Both pass through verbatim; nothing is stripped.

---

Tools

All 52 tools the MCP server exposes (generated from tools/list). Invoke any by asking your agent in plain English, or call the API/CLI directly.

Read & explore

• xlsx_read — read an .xlsx file by path and return a rendered markdown/JSON/SQL representation. Also reads a live Google Sheet: pass source:"gsheets" with the spreadsheet_id and a read-only Google OAuth token you supply (token-injected — read-only, no write; the server never mints or brokers Google credentials). Same rendered output as reading the equivalent .xlsx.
• xlsx_read_handle — read a workbook that has already been uploaded to the server via the chunked upload flow, by its server-side cache handle, WITHOUT re-transferring the bytes. Returns the same shape as xlsx_read (text / json / markdown) but skips the file_b64 round-trip.
• xlsx_validate — cross-engine consistency check on a LOCAL .xlsx file — runs the workbook through TWO independent renderers (@protobi/exceljs and @cj-tech-master/excelts) and reports cell-level divergences.

Inspect structure

• xlsx_charts — List every chart in a LOCAL .xlsx file with type (bar / line / pie / scatter / area / doughnut / radar / stock / surface / bubble), title, axis titles, and per-series formula refs (the cell ranges the chart pulls from). Sheet attribution via the OOXML drawing rel chain.
• xlsx_comments — list every cell comment in a workbook — both legacy notes (yellow stickies, cell.note) AND modern threaded comments (multi-author conversations stored separately in the OOXML zip). Per entry: kind, sheet, cell, author, text, plus any reply thread.
• xlsx_conditional_formats — list every conditional formatting rule in a workbook — color scales, data bars, icon sets, formula-based highlights, top-N, duplicate / unique values, contains-text, time-period, above-average. Per rule: range, type, operator, formulae, priority, stopIfTrue.
• xlsx_data_validations — list every cell-level data validation rule (dropdowns, numeric/date bounds, text-length caps, custom formulas) defined in a workbook — the constraints that Excel enforces when a human types into the cell.
• xlsx_describe — pandas-style df.describe() per column — count, nulls, unique, min/max/mean/std for numerics, dtype with purity score.
• xlsx_external_links — list every external workbook reference this file depends on — =[Budget.xlsx]Sheet1!A1 style formulas. Per link: target path (decoded), classification (http / network share / absolute / relative), sheets pulled from the external workbook, count of cached cell values, and defined-name references.
• xlsx_form_controls — list every form control (Check Box, Button, Drop-down, List Box, Option Button, Scroll Bar, Spinner, Label, Group Box) in a workbook with the linked cell, current value, dropdown source range, and min/max/step bounds where applicable.
• xlsx_formulas — extract every formula in a LOCAL .xlsx workbook — cell coord (A1), formula text, cached result. openpyxl-style read-only metadata.
• xlsx_hyperlinks — list every hyperlink in a workbook with its anchor cell, target URL/anchor, display text, tooltip, and a kind classifier (external / internal / mailto / unknown).
• xlsx_images — List every embedded image in a LOCAL .xlsx file with format (png / jpg / gif / svg / bmp / tiff / emf / wmf), size in bytes, sheet attribution, and anchor cell range (the cells the image floats over). Reads xl/media/* + xl/drawings/* directly.
• xlsx_list_sheets — list sheet names, dimensions, and visibility for a LOCAL .xlsx file.
• xlsx_macros — Inspect xlsm / xlsb workbooks for VBA macro presence, vbaProject.bin size, and likely module names (ThisWorkbook / Sheet / Module / Class / UserForm via heuristic UTF-16LE scan). Returns short safety advice the LLM should relay to the user.
• xlsx_merged_cells — list every merged-cell region with master-cell value, range, span dimensions, and kind heuristic ("header" / "horizontal" / "vertical" / "block"). Pandas reads merged cells by dropping the relationship — it sees one value in the master cell and three blanks alongside. xlsx_merged_cells is the layout-aware view: "A1:D1 is ONE cell that says Q4 2024" rather than four cells where three are mysteriously empty.
• xlsx_named_ranges — list all defined names (named ranges) in a LOCAL .xlsx workbook — name, scope (workbook or sheet), kind (cell / range / formula), reference.
• xlsx_pivot_tables — List every PRE-EXISTING pivot table definition in a LOCAL .xlsx file (the ones an Excel user already built). Per pivot: sheet, name, location range, source range (or named-range / table reference), row / column / page fields, and data fields with their agg function (sum / count / average / max / min / product / stdDev / etc.).
• xlsx_print_settings — surface "what would Excel print right now" per worksheet — print area, orientation, paper size (A4 / Letter / Legal / Tabloid / etc.), scale or fitToPage, margins, headers/footers split into Excel's L/C/R zones, print titles (rows / columns repeated on every page), manual page breaks, plus B&W / draft / centered flags.
• xlsx_properties — Surface the workbook's identity card from a LOCAL .xlsx file. Core: creator, last_modified_by, created/modified/lastPrinted timestamps, title, subject, company, manager, keywords, category, description. Application: app name + version, doc security label, hyperlink base. Custom: every user-defined Info > Properties entry (Department, ReviewedBy, ApprovalRequired, etc.) with type tag and value.
• xlsx_protection — Surface every protection setting in a LOCAL .xlsx file so an agent knows what it can and cannot edit. Workbook-level (lockStructure, lockWindows), per-sheet (protected? password? hidden state?), per-action allow/block list (formatCells, sort, insertRows, pivotTables, etc.), and per-cell unlocked / hidden samples — these are the cells a human would actually be allowed to type into when the sheet is otherwise read-only.
• xlsx_schema — infer column schema of a LOCAL .xlsx file — types, nullable flags, header row, sample values.
• xlsx_slicers_timelines — List every slicer (interactive filter button) and timeline (date-range filter visual) in a LOCAL .xlsx file with their captions, source bindings (table column or pivot table), and timeline granularity (years / quarters / months / days) plus the currently-selected date range.
• xlsx_styles — surface cell formatting (number formats, fonts, fills, alignment) so an agent knows what a cell LOOKS like, not just its raw value. Default mode: per-sheet rollup of top-N number formats / fonts / fills with counts. Detailed mode (opt-in, capped at 1000 cells): per-cell breakdown for narrow queries.
• xlsx_tables — list every Excel ListObject ("Format as Table" structures) in a LOCAL .xlsx workbook — name, sheet, range, header/totals flags, columns.
• xlsx_workbook_views — Surface the UI state of a LOCAL .xlsx file — what a human sees when they open it in Excel. Per sheet: visibility (visible / hidden / veryHidden), view state, zoom, active cell + selection, frozen-pane breakdown, gridlines / row-col headers / ruler / RTL flags, tab color. Workbook level: which sheet is active when Excel opens.

Query & analyze