Using the raw HTTP API.

Every xlsx-for-ai tool is a plain HTTP endpoint you can call from any language — no SDK, no upload UI.

The MCP client is the easy path for Claude, Cursor, and other agents. But if you're integrating directly, the same 54 tools are a versioned HTTP API. You can browse the reference without a key; calling a tool needs a key, and the section below shows how to get one.

Signing in

Sign-in is with Google only. In an assistant or editor, install the package (npm install -g xlsx-for-ai@latest, version 4.2.1 or later) and make your first request. The package answers with a sign-in link shown right there in the assistant: open it, sign in with Google, then ask again. This works the same in a desktop app or editor with no terminal, and nothing needs a second machine. From a terminal you can also run xlsx-for-ai login, which prints a short code and a verification address to approve in your browser. Either way the client stores the key it receives.

Keys made without signing in (by earlier versions, or by registering with no credentials) still work. Signing in is recommended, and we will give notice before anything about those keys changes.

Plans and limits

There are two plans, and both are counted in files, never in file size. Xlsx Pro Free is 500 files a month for the first 1,000 people who sign in. Otherwise you get a 10-file trial, then Xlsx Pro at $25 a year for 10,000 files a month.

File-size limits are the same for everyone and are not something you can buy: .xlsx 100 MB, .csv 200 MB, .xls 100 MB, .xlsb 10 MB, any other type 10 MB. For a file over its limit, split it or convert it; the large-files page says how.

Claude Code plugin (one command)

In Claude Code 2.1.292 or later, one command adds the plugin and installs it. The plugin tells Claude what the hosted xlsx-for-ai tools do and when they fit: 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

Then run /reload-plugins (or restart Claude Code), open /mcp, choose plugin:xlsx-for-ai:spreadsheets and sign in with Google once. If your Claude Code is older, run claude update first.

Claude app on claude.ai (nothing to install)

xlsx-for-ai is listed in the Claude connector directory. Open the directory, find xlsx-for-ai, click Connect, and sign in with Google when asked.

Any other MCP client that accepts a server address can add the hosted address https://api.xlsx-for-ai.dev/mcp as a remote server.

https://api.xlsx-for-ai.dev/mcp

Getting a key over plain HTTP

POST https://api.xlsx-for-ai.dev/api/v1/clients (no auth) returns { client_id, api_key }; then call any tool with an Authorization: Bearer <api_key> header. A key made this way has not signed in, so signing in (above) is recommended.

# 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

Discover the whole API — no key required

The same governed contract is served read-only from two routes, so you can explore before you register:

• GET /api/v1/reference
  A self-contained human HTML reference for all 54 public-stable tools plus the 2 documented session tools (xlsx_read_handle, xlsx_session_set_validations), 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.

Errors and the convert refusal

Every error body has the same shape: { "error": { "code", "message" } }. The code is the stable key to branch on, and the message is the self-correcting detail that says what was wrong and what to change. A few codes add a documented extra field, such as available_sheets when a sheet name is not found, but there is no finer error-subtype field in the response.

When our own engine cannot produce the output you asked for from an xlsx, xls, csv or json file (most notably to=xlsx), xlsx_convert returns a typed HTTP 501 with the error code capability_gap and does not fall back to a compatibility library. This is not a client error and it is not transient, so retrying the same file does not help. Through the MCP connector the same refusal arrives as a tool result with isError set to true, carrying the same message. Formats such as ods, xlsb, fods and the xls (BIFF8) write target are served by the legacy path and are unaffected.

Prefer the MCP client?

If your agent speaks MCP, skip the HTTP wiring entirely — install the client and register it with two commands:

npm install -g xlsx-for-ai
claude mcp add xfa -- xlsx-for-ai-mcp

Full docs and the complete tool reference are on the GitHub repository and the npm package page.

Getting a file in and a result out

Two surfaces take a file in and give a result back: the MCP connector at https://api.xlsx-for-ai.dev/mcp, and the REST API at POST /api/v1/tools/<name>.

MCP connector: getting a file in

A chat host does not pass attached files to a connector, so the file reaches the tool one of three ways, in order of preference:

1. A share link. Pass a Google Sheets, Google Drive, Dropbox or OneDrive share link, or another https link, as file_url. A Google Sheets link must be shared as “Anyone with the link” (Viewer): the server fetches Google’s own .xlsx export and cannot sign in to Google as you. If the sheet is not shared that way, the tool result says so and tells you to change the sharing or to download it as .xlsx and upload it.
2. An upload page. If there is no link, call xlsx_upload_link. It returns a one-time upload page; you pick the file there, and the returned file_handle can be passed to any tool.
3. The local package, for a large file on your own computer. The xlsx-for-ai npm package is an MCP server for desktop and coding clients. It reads from disk, so there is no browser upload. Its default limit is 50 MB, adjustable with XFA_MAX_FILE_MB.

Reading a private Google Sheet through the live Google Sheets API (xlsx_read with source: "gsheets") needs a Google OAuth access token with the spreadsheets.readonly scope, supplied by the caller.

A link is read as the sheet stands at that moment, with Google’s calculated values. To recalculate after changing inputs, call xlsx_write with the workbook as the base plus the changed cells, then call xlsx_eval on the returned file_handle.

MCP connector: getting a file back

Every tool that produces a file (xlsx_write, xlsx_convert, and the cleaning, redaction, repair, receipt and stamp tools) returns:

• a download link in its result text;
• an MCP resource_link content block;
• _meta.download_url, _meta.download_expires_at, _meta.file_name and _meta.file_handle;
• _meta.file_b64, which is still there.

The link is a signed, unguessable token. It works for about one hour, serves only the file of the account that produced it, and then returns 410. No copy is stored and no link is returned when the account’s consent level is none or the request carries the header x-xfa-privacy: strict. GET /download/<token> serves a file produced through the MCP door.

Exporting a Google Sheet to .xlsx

xlsx_convert with to: "xlsx" returns the workbook as Google exported it. Google Sheets functions that Excel does not support (for example QUERY, IMPORTRANGE, GOOGLEFINANCE and ARRAYFORMULA) do not stop the export. Those cells keep the value they had in the sheet and do not recalculate in Excel. The result carries a visible line starting “Google Sheets notice:” and a structured _meta.google_sheets_notice naming each function and where it is used. A workbook with none of them carries no notice.

Starter prompts

The connector offers eight starter prompts through MCP prompts/list. They show in the connector’s menu in Claude and as slash commands in Claude Code. Each one starts with the file hand-off above: it uses a link if you give one, and otherwise asks for an upload page link. The names are welcome, check_my_spreadsheet, recalculate_and_compare, read_exact_values, compare_two_versions, clean_my_data, write_xlsx_with_formulas and google_sheet_to_xlsx.

check_my_spreadsheet (“Check my spreadsheet for errors”) takes an optional file_url and runs xlsx_check on the workbook.

Choosing the tool list

tools/list returns every tool. The main tools come first, in this order: xlsx_read, xlsx_eval, xlsx_write, xlsx_convert, xlsx_list_sheets, xlsx_upload_link. The rest follow by name. A client that wants a short list can send the header x-xfa-toolset: core or connect to /mcp?toolset=core. Every tool stays callable by name.

REST API

The REST API is unchanged. Send file_b64 to POST /api/v1/tools/<name> and receive produced bytes in _meta.file_b64.