Xlsx For AI

xlsx-for-ai

*Short name: xfa — a real CLI command (xfa , 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-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.

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 returns { client_id, api_key }. Call any tool with Authorization: Bearer . 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`](https://api.xlsx-for-ai.dev/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`](https://api.xlsx-for-ai.dev/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 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 calculatio