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. 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.
In Claude Code, one command:
claude plugin install xlsx-for-ai --marketplace senoff/xlsx-for-ai
Then run /reload-plugins (or restart Claude Code), open /mcp, choose plugin:xlsx-for-ai:spreadsheets and sign in once. Needs Claude Code 2.1.292 or later (claude update if yours is older). More on the plugin is under Claude Code plugin below.
In the Claude app (claude.ai): find xlsx-for-ai in the connector directory at claude.ai/directory and click Connect.
The npm package (Claude Code, Cursor, Claude Desktop and others):
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-xlsxalias 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.
Claude Desktop
Claude Desktop reads files, but it cannot recalculate formulas, read a very large workbook exactly, or hand back a real .xlsx. The xfa server adds those. The install does not touch Claude Desktop, so add the server yourself. Install the package first (npm install -g xlsx-for-ai), then open the config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
(In Claude Desktop: Settings → Developer → Edit Config opens it.) Add xfa under mcpServers, keeping any servers already there:
{
"mcpServers": {
"xfa": {
"command": "xlsx-for-ai-mcp"
}
}
}
Fully quit and reopen Claude Desktop. Verify: ask "what MCP tools do you have?" and confirm xfa shows 52 xlsx_* tools. Your first request answers with a sign-in link and a short code: open the link, approve, then ask again.
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 connects your agent to the hosted xlsx-for-ai tools for spreadsheet files and links (.xlsx, .xlsm, .xls, .csv, .tsv, a Google Sheet) and tells it when they help: when the answer depends on formula results, on whether saved values are current, or on handing back a working spreadsheet file.
claude plugin install xlsx-for-ai --marketplace senoff/xlsx-for-ai
That one command adds the marketplace and installs the plugin. It needs Claude Code 2.1.292 or later; run claude update first if yours is older.
Then, once: run /reload-plugins (or 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 when the xlsx-for-ai tools help, 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
spreadsheetsskill 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: passsource:"gsheets"with thespreadsheet_idand 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!A1style 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.
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 ofindex, columns are unique values ofcolumns, and cells are an aggregation ofvalues.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, ormigrate) 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).
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, and it computes over 350 Excel functions today, plus the functions only Google Sheets has, with more added as they are built. Coverage spans the standard function families: Math & trig, Statistical, Financial, Date & time, Text, Logical, Lookup & reference, Information, and Engineering. The full served list is on the Functions section of https://xlsx-for-ai.dev.
A function the engine does not serve yet returns an honest "not supported yet" error, never a guessed value. Functions that reach outside the workbook, such as WEBSERVICE, RTD and STOCKHISTORY, are not served, so a recalc can't reach off-workbook.
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_diffproduces identical output for identical inputs — safe to version-control, safe to assert against in CI. - Confidence-rated schema inference.
xlsx_schemareturns 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 / Claude Desktop / 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 — workbook capture is off for every account (since 2026-10-14). XFA_PRIVACY=strict also turns off the 60-minute download copy of files a tool produces. 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.
