xlsx-for-ai

# xlsx-for-ai

[![xlsx-for-ai MCP server](https://glama.ai/mcp/servers/senoff/xlsx-for-ai/badges/score.svg)](https://glama.ai/mcp/servers/senoff/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.

```bash
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](#migration-from-15x) 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](#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:

```bash
npm install -g xlsx-for-ai
```

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

```bash
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`

```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`

```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:

```json
{
  "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`

```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`

```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](#what-it-costs) for the limits.

```bash
# 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 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.

```bash
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