xlsx-for-ai（xfa）：为 Claude 等 LLM 智能体提供 Excel 可靠读写层的 MCP 工具

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. A soundness check (xlsx_validate) flags 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 (it still needs an internet connection, because the files are read by the hosted service); 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 run needs a one-time sign-in. In an editor or desktop app, your first request answers with a sign-in link and a short code: open the link, approve, then ask again. Or run xlsx-for-ai login in a terminal first (see First-run sign-in). Keys created by older versions keep working for now. When that changes, the sign-in link appears in the same place, so there is nothing to do ahead of time.

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. Sign in with the OAuth device flow (RFC 8628) at https://api.xlsx-for-ai.dev/oauth (/oauth/reg, /oauth/device/auth, /oauth/token, with resource=https://api.xlsx-for-ai.dev/mcp), then POST https://api.xlsx-for-ai.dev/api/v1/clients with Authorization: Bearer <access token> returns { client_id, api_key }. Call any tool with Authorization: Bearer <api_key>. Anonymous keys from earlier versions still work during the transition. See What it costs for the limits.

# Legacy keyless registration (still accepted during the transition; new integrations
# should use the device-flow sign-in above), 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

Files that are too large, and requests over your limit, come back as a typed JSON error with an upgrade field where a plan would help (see below).

Rate-limited, over-limit 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.

Every error body is exactly that shape: error.code is the stable, machine-readable key to branch on, and error.message is the self-correcting detail that says what was wrong and what to change. A few codes add a documented extra field (for example available_sheets on a sheet-not-found refusal, or upgrade on a paywall refusal), but there is no finer error-subtype field on the wire; the server keeps a finer attribution for its own audit only.

Convert can refuse with a typed 501. xlsx_convert converts xlsx, xls, csv and json inputs with the server's own engine only. When that engine declines a conversion of one of those inputs (for example some to=csv conversions of an .xlsx whose cells use a display format or an uncached formula the engine cannot reproduce exactly; the same file usually still converts with to=xlsx or to=json), the API returns HTTP 501 with error.code capability_gap and a message of the form "xlsx_convert isn't yet supported by our own engine for .xlsx files, and we don't fall back to a full-workbook recompute on this file type ...". It does not silently fall back to a compatibility library. It is not a client error and not transient, so retrying the same file does not help. Through the hosted MCP connector the same refusal arrives as a tool result with isError: true carrying that message. Exotic formats (ods, xlsb, fods, and the xls/BIFF8 write target) are still served by the legacy path and are unaffected.

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.

Claude Code plugin

A Claude Code plugin makes your agent come to the hosted xlsx-for-ai tools first whenever a spreadsheet is involved (.xlsx, .xlsm, .xls, .csv, .tsv, a Google Sheet), instead of reading the file with code, installing a package or converting it locally.

claude plugin marketplace add senoff/xlsx-for-ai
claude plugin install xlsx-for-ai@xlsx-for-ai

Then, once: start Claude Code, run /mcp, choose the plugin:xlsx-for-ai:spreadsheets server and sign in in the browser. The plugin connects to the hosted endpoint https://api.xlsx-for-ai.dev/mcp (OAuth sign-in) and asks for the full tool list.

Version 0.1.1 renamed the server key in the plugin's .mcp.json from xlsx-for-ai to spreadsheets, so /mcp now shows plugin:xlsx-for-ai:spreadsheets instead of plugin:xlsx-for-ai:xlsx-for-ai. Claude Code reads the key from the plugin's own .mcp.json and nothing else reads it. If you are on 0.1.0, sign in once after updating, because the server has a new name.

What it does:

• Prints a short text at session start (startup, resume, clear and compact) that says to use the xlsx-for-ai tools first for any spreadsheet, why, how to hand a file over from Claude Code, and every tool by name.
• Sends Shopify export files (products, inventory, collections, redirects, metafields) to the shopify_* tools, which build a file ready to import into Shopify (plus Google, Amazon, eBay and UPS feed files). They work on the file you give them and hand a file back; you import the result yourself.
• Adds a spreadsheets skill that applies when spreadsheet files are in play.
• Connects Claude Code to the hosted server.

What it does not do: it ships no engine. No calculation, parsing or conversion code of ours runs on your machine; the only thing that runs locally is cat printing the session-start text file. Files you give the tools are sent to the hosted service (a link, or a one-time upload). The plugin lives in claude-code-plugin/; the session-start text is generated from claude-code-plugin/tool-manifest.json by scripts/plugin/generate-session-start.js, and a test fails if they disagree. On Windows the hook works in Git Bash or PowerShell (cat is available in both).

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

Read / write

Pandas-parity (compute fresh aggregates)

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

Integrations

Integrity verification

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 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 — soundness check on a LOCAL .xlsx file — parses the workbook with the server's own OOXML engine and reports whether it loads cleanly (truncated zip, encrypted container, no worksheets, or a damaged sheet body each fail), with a per-sheet structural summary.

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

• xlsx_aggregate — pandas-style df.groupby([cols]).agg({col: func}) on a LOCAL .xlsx file. funcs: sum / mean / min / max / count / count_distinct.
• xlsx_diff — compute a semantic diff between two LOCAL .xlsx files — cell-level deltas, formula changes, added/removed rows.
• xlsx_eval — evaluate Excel formulas against a LOCAL .xlsx file with our own recalc engine. xlwings-style.
• xlsx_filter — pandas-style row filter on a LOCAL .xlsx file with predicates AND-combined: eq/ne/gt/gte/lt/lte/contains/in/is_null/not_null.
• xlsx_pivot — pandas-style pivot_table() on a LOCAL .xlsx file — reshape a flat table into a 2D matrix where rows are unique values of index, columns are unique values of columns, and cells are an aggregation of values.
• xlsx_sort — pandas-style df.sort_values() on a LOCAL .xlsx file with multi-column sort and per-column direction (asc/desc, default asc).
• xlsx_topology — one-call workbook orientation. Returns sheets × dimensions × formulas × named ranges × tables × validations × hyperlinks × merges in one shot, plus feature flags (macros / external refs / pivots / LAMBDA / dynamic arrays).
• xlsx_value_counts — pandas-style Series.value_counts() on one column of a LOCAL .xlsx file — count each unique value, sorted by frequency desc, with percentage.

Clean & fix

• xlsx_data_clean — AI-native data cleaning for a LOCAL .xlsx file. Scans for the seven most common data-grime issues — NA variants (N/A, NA, null, -), merged-cell residue, type-coercion mistakes (numeric-as-text / date-as-serial / leading-zero stripped), trailing-row noise (footers / totals), header-row-not-first (preamble before headers), encoding glitches (UTF-8-as-CP1252 mojibake), and duplicate column headers — and either flags them (diagnose mode) or applies deterministic fixes (execute mode).

Convert

• xlsx_convert — universal spreadsheet format converter. Reads ANY of 25+ input formats (xlsx, xlsb, xlsm, xls, ods, fods, numbers, csv, tsv, dbf, lotus 1-2-3, quattro pro, sylk, dif, html, rtf, etc.) and emits ANY supported output format (xlsx, csv, json, md, html, etc.).

Write (new file)

• xlsx_redact — redact PII and sensitive values from a LOCAL .xlsx file before sharing or archiving.
• xlsx_write — create or update a LOCAL .xlsx file from a structured spec.

Integrity & verification

• xlsx_healer_cure — Apply ONE specific cure operation against a diagnosed workbook. Operations: rename_move (rewrite ref paths), pattern_bulk (regex-style ref rewrites), source_deleted_freeze (replace broken refs with cached values), source_deleted_redirect (point at a replacement file), source_deleted_localize (snapshot external source into a local copy), permission_denied (strip credentials), structure_changed (rewrite formulas for moved cells), format_change (re-link after extension change), make_standalone (fully dereference all externals). Returns cured workbook bytes + receipt.
• xlsx_healer_diagnose — produce a structured diagnostic report of external references that are broken or at risk in a workbook. Returns five classes of finding: (1) external-workbook references that can't resolve, (2) defined-name external refs, (3) Power Query connections with embedded credentials, (4) #REF! propagation maps from upstream breakage, (5) multi-hop chains (workbook → workbook → workbook). Findings carry reference_id keys that downstream cure operations key on.
• xlsx_healer_intent — Goal-driven healing. Caller declares an INTENT (make-it-work, make-standalone, or migrate) instead of a specific cure operation; Healer plans the operation sequence + applies it. make-it-work: minimum surgery to clear errors. make-standalone: fully de-externalize (snapshot every external dep). migrate: rewrite all references against a from/to prefix pair. Returns the planned operations, cured bytes, and an unactionable list.
• xlsx_healer_simulate — simulate recipient-side accessibility of a workbook's external references. Given a list of paths the recipient CAN see (accessible_paths), returns which references will still resolve at the recipient end and which will break (and why). Read-only; produces no output workbook.
• xlsx_receipt — Attach an AI-generation receipt to a LOCAL .xlsx file — a cryptographic attestation embedded in docProps/custom.xml that says "this file was generated by THIS agent, at THIS time, against THESE inputs." Returns the receipted workbook as base64 in _meta.file_b64; pass out_path to write to disk.
• xlsx_stamp — Sign a LOCAL .xlsx file with a "workbook integrity verification" stamp — a cryptographic attestation embedded in docProps/custom.xml that says "this file was generated by these tools, passed these N specific checks, signed at this time, and hasn't been tampered with since." Factual claims only (never an opinion-shaped seal of approval). Returns the stamped workbook as base64 in _meta.file_b64; pass out_path to write to disk.
• xlsx_verify_receipt — verify a workbook's embedded AI-generation receipt. Returns whether the signature is valid, whether the recomputed content hash matches the hash IN the receipt, and the full caller-declared claims (agent identity, generation timestamp, source-file hashes, prompt hash, MCP tools called, description).
• xlsx_verify_stamp — verify a workbook's embedded integrity-verification stamp. Returns whether the cryptographic signature is valid, whether the workbook bytes match what was signed (recomputed hash vs hash IN the stamp), and the full check-result content of the stamp.

Integrations

• xlsx_post_slack — upload a local .xlsx file to a Slack channel as a file attachment, with an optional accompanying message.
• xlsx_post_teams — Upload a local .xlsx file to a Microsoft Teams channel as a file attachment, with an optional accompanying message.

Session

• xlsx_session_set_validations — configure per-session data-validation rules the server will apply to subsequent calls in the same session (e.g., reject rows missing required columns, enforce enum values on a category column, range-bound numeric inputs). Stateful — affects this session only.

One-call capstone

• xlsx_doctor — ONE-CALL workbook health report for a LOCAL .xlsx file. Scans for macros, external workbook references, hidden / veryHidden sheets, missing creator metadata, large embedded images, and surfaces interesting feature flags (LAMBDA, dynamic arrays, pivot cache, slicers, threaded comments). Findings ranked HIGH / MEDIUM / LOW. Plus quick_facts: sheet count, formulas, named ranges, merges, hyperlinks, validations, images, file size.

Functions

xlsx_eval recalculates formulas with our own recalc engine — 128 Excel functions today, and growing (we certify more each week). Coverage spans the standard function families: Math & trig, Statistical, Financial, Date & time, Text, Logical, Lookup & reference, Information, and Engineering.

The engine has no INDIRECT, WEBSERVICE, RTD, DDE — there is no dynamic-reference, network, or external-data function in the set, so a recalc can't reach off-workbook. The absent functions are the sandbox boundary.

FP&A workflows

xlsx-for-ai is built for agents working on real financial spreadsheets. Common workflows:

Budget vs. actual variance analysis

xlsx_read → extract actuals and budget → agent computes variances → xlsx_write → deliver updated workbook

Month-end reconciliation

xlsx_read (bank export) + xlsx_read (GL extract) → agent matches rows → xlsx_diff → audit trail of unmatched items

Audit-trail extraction

xlsx_schema → identify change-log columns → xlsx_read with sheet filter → agent summarizes changes by author/date

Multi-entity consolidation

xlsx_read × N entity files → agent aggregates → xlsx_write → consolidated workbook with intercompany eliminations noted

Pre-share PII redaction

xlsx_redact → strips SSNs, emails, employee IDs → redacted file safe for external distribution

These workflows are the reason tool descriptions are FP&A-legible: when a developer builds an agent for a finance team, the agent's LLM reads the tool descriptions and routes correctly without extra prompt engineering.

Reliability features

• Deterministic diffs. xlsx_diff produces identical output for identical inputs — safe to version-control, safe to assert against in CI.
• Confidence-rated schema inference. xlsx_schema returns type confidence scores alongside inferred types. Agents can branch on confidence rather than trusting a blind guess.
• Audit trail. Every tool call — success or failure — is logged server-side with timestamp, client ID, endpoint, file size, latency, and error class.
• Hardened input validation. Four pre-engine guards on every uploaded buffer: billion-laughs XML bomb defense, control-character stripping, worksheet buffer ceiling (slow ZIP-bomb defense), and typed error chaining. Applied before the xlsx engine sees any bytes.
• Agent-readable errors. Rate-limit and validation errors return structured JSON — agents can read them and prompt the user intelligently, not just surface a status code.

Privacy

Files are transmitted to https://api.xlsx-for-ai.dev over HTTPS and processed in memory. Files are not persisted beyond the duration of a single request. Sign-in is with a Google account; the address is used only to identify your account, and no password is stored.

See PRIVACY.md for the full data-handling policy.

What it costs

All the tools are included. You sign in once on first use (a link and code in your editor, or xlsx-for-ai login in a terminal). The first 1,000 people to register get 500 files a month free. Everyone after gets 10 free files, then $25 a year for 10,000 files a month. Sign-in is with Google. File-size limits are the same on every plan: .xlsx up to 100 MB, .xls up to 100 MB, .csv up to 200 MB. The service shows these limits in its own messages when you reach them.

License

The npm client (xlsx-for-ai, this package) is MIT. The hosted API server (xlsx-for-ai-server) is proprietary — engine IP, rendering pipeline, and semantic-diff algorithm are not open source.

Architecture

agent (Claude Code / Cursor / Continue / Zed / Windsurf / custom)
  └── MCP stdio
        └── xlsx-for-ai-mcp  (this package, ~200 lines)
              └── POST /api/v1/tools/<name>  →  api.xlsx-for-ai.dev
                    └── server-side engine (own OOXML/CSV engine, formula eval, schema inference, redaction)

Requirements: Node.js 22+. 1.5.x line stays maintained on main for users who cannot upgrade.

First-run sign-in

xlsx-for-ai login

Prints a link and a short code. Open the link in any browser, sign in with Google, approve, and the CLI stores your key in ~/.xlsx-for-ai/config.json. Running any command with no stored key in an interactive terminal starts the same flow automatically. xlsx-for-ai login --force signs in again.

Using it from an editor or desktop app (no terminal). You do not need to run anything first. The first time you ask the assistant to use a spreadsheet tool, it replies with a sign-in link and a short code instead of an answer. Open the link in a browser, check the code matches, and approve. Then ask again: the request works, with no restart. If you ask again before approving, you get the same link and code. If the link runs out (about 15 minutes) or you decline it, the next request gives you a fresh one.

A terminal command with no screen to answer on (for example a script, or a command run by another program). The command prints the link and code to the error stream and waits up to 60 seconds for you to approve. Approve in time and it carries on with your request. If you do not, it stops and tells you to approve and then run the same command again. The second run picks up the same code, so there is nothing new to copy, and it finishes at once if you have approved in the meantime. To change the wait, set XFA_LOGIN_WAIT_SECONDS (for example XFA_LOGIN_WAIT_SECONDS=120).

In automated runs (CI), and in any run where you set XFA_NONINTERACTIVE=1, nothing waits and no sign-in is started. With no key the command stops straight away and says so. For an automated run, sign in once on a computer where you have a terminal, then pass the api_key value from ~/.xlsx-for-ai/config.json to the run as the environment variable XLSX_FOR_AI_KEY (keep it in your secret store). That variable wins over the saved file when both exist.

If the saved key is rejected. In an editor or desktop app, the next request shows a fresh sign-in link and keeps your saved key until you approve the new one. In a terminal, run xlsx-for-ai login --force.

Messages you may see. When you hit a usage limit, the message comes from the service itself. A 402 gives its message and a link to upgrade, and a 429 gives its message and when to try again. A 501 means that function is not built yet, nothing is wrong with your file, and trying again will not help; the terminal command exits with code 5 for it (3 means the service could not be reached or had a fault, 4 means a file or link problem, 2 means a usage mistake, 1 anything else).

Updating. If this copy cannot update itself (a read-only install, a container), the tool results say a newer version exists and give the command to update. An assistant that can run commands can do it for you; otherwise run npm install -g xlsx-for-ai@latest in a terminal and restart the app. Set XFA_NO_AUTO_UPDATE=1 to turn the self-update and this notice off.

Links are not files. This package reads files saved on your computer only. If you give it a web link or a Google Sheets link instead of a file path, it says so. Download the file and give its path, or use the hosted xlsx-for-ai connector, which can open links directly.

Running in Docker. The image no longer skips sign-in. The first request prints a sign-in link and code. Your key is stored in the container at /home/node/.xlsx-for-ai, so mount a volume there to keep it between runs, for example -v xfa-config:/home/node/.xlsx-for-ai.

Keys minted by versions before 4.1.0 keep working for now. When the service marks a key as one that will stop, the tool result says so in plain words; no date is promised here.

Config

Stored at ~/.xlsx-for-ai/config.json. Created automatically on first run. Beside it, pending-login.json holds a sign-in that was started and is waiting for your approval (so the rerun shows the same code); it is removed once you are signed in or the code ends. The folder can be moved with XFA_CONFIG_DIR.

{
  "client_id": "<uuid>",
  "api_key": "<opaque>",
  "registered_at": "2026-05-05T00:00:00.000Z",
  "telemetry": false,
  "consent_version": 1
}

Telemetry is opt-in:

xlsx-for-ai --enable-telemetry
xlsx-for-ai --disable-telemetry
xlsx-for-ai --telemetry-status

Privacy modes — error-capture is off by default; when enabled, cell values are stripped before anything is retained (structure only, 30-day TTL, never used for training). XFA_PRIVACY=strict opts out entirely. See PRIVACY.md:

# Per-session flag (applies to all tool calls in the CLI invocation)
xlsx-for-ai --privacy=strict myfile.xlsx

# Environment variable (applies globally to all requests in the process)
XFA_PRIVACY=strict xlsx-for-ai myfile.xlsx

# In MCP server config (applies to all tool calls from the MCP server):
# Set XFA_PRIVACY=strict in your MCP server's env block

Delete the config to reset your client ID and API key:

rm ~/.xlsx-for-ai/config.json

Migration from 1.5.x

The config file at ~/.xlsx-for-ai/config.json is extended in-place — existing telemetry consent is preserved.

Security

See SECURITY.md. All file content is transmitted to https://api.xlsx-for-ai.dev over HTTPS. Files are not retained beyond the duration of a single request.