mcp-spreadsheet

MCP server for spreadsheets: read, query, edit and convert xlsx, csv and Excel files, and builds a new spreadsheet from rows in a chat. Read, query, edit and convert xlsx and csv files safely.

Works with Claude Desktop, Claude Code, Cursor and any Model Context Protocol client. Runs on your own machine, or hosted with no install.

Product page: https://mcp.zovo.one/s/spreadsheet — capabilities, free limits and supported installation paths.

Install

Hosted, nothing to install. Get a token from https://mcp.zovo.one/mcp/connect?acq=github (the connect page) or https://mcp.zovo.one/mcp/token (the same token as JSON); a free anonymous one is issued on the spot and a Pro key works the same way. Then point an MCP client at https://mcp.zovo.one/mcp/spreadsheet over streamable-http and send the token as Authorization: Bearer <token>.

If your client cannot set headers, put the token in the path instead: https://mcp.zovo.one/mcp/spreadsheet/t/<token>. Both forms work. The bare URL with no token answers 401 on tools/call, so the token is not optional.

Claude Desktop, one click. Download spreadsheet.mcpb from the bundle catalog and double-click it.

From source. The mirror is self-contained: every @theluckystrike/* dependency is vendored, so a fresh clone builds with no extra setup.

git clone https://github.com/theluckystrike/mcp-spreadsheet.git
cd mcp-spreadsheet
npm install && npm run build

Then point your client at the built entry point:

{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-spreadsheet/dist/index.js"]
    }
  }
}

@theluckystrike/mcp-spreadsheet is not published on npm yet, so an npx -y @theluckystrike/mcp-spreadsheet command will fail. The three paths above are the working ones and each is exercised by CI.

Read-only mirror of mcp-servers/servers/spreadsheet. See MIRROR.md.

Featured on Awesome MCP Servers - directory listing | live hosted endpoint, free tier, no signup.

Hand your AI assistant a spreadsheet and talk to it. Point it at any .xlsx, .xlsm, .xlsb, .xls, .ods, .csv or .tsv file on your machine and ask what is in it, filter it, compute a new column, or save it in another format. It handles the messy parts of real files for you: it guesses which row holds the headers, sniffs whether a CSV is separated by commas, semicolons or tabs, keeps quoted commas and newlines intact, reads numbers out of $1,250.00 style text, and reports per-column types and empty counts. It never edits your original file: every write goes to a new path unless you explicitly choose overwrite. Nothing leaves the machine, and there is no API key to get.

In the official MCP Registry (io.github.theluckystrike/excel-spreadsheet-xlsx-csv).

Listed on the AI Product Index - live remote endpoint at mcp.zovo.one/s/spreadsheet, free tier, no signup.

Read, query and extend real spreadsheets from chat without ever touching the original file.

Related MCP server: SheetForge MCP

60-second install

Use spreadsheet.mcpb v0.22.9 in Claude Desktop. Published checksums and the versioned download catalog identify the exact release. The npm package is not published.

For a source installation, use Node.js 22 or newer and build the shared dependency first:

git clone https://github.com/theluckystrike/mcp-servers.git
cd mcp-servers
npm ci
node scripts/bootstrap-timezone.mjs
npm run build -w packages/mcp-license -w servers/spreadsheet

Merge this entry into Claude Desktop's mcpServers, or into .cursor/mcp.json for Cursor. Replace the absolute path with your checkout:

{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["/absolute/path/mcp-servers/servers/spreadsheet/dist/index.js"]
    }
  }
}

For Claude Code:

claude mcp add spreadsheet -- node /absolute/path/mcp-servers/servers/spreadsheet/dist/index.js

To run in Pro mode set MCP_LICENSE_KEY in the same config block, or call license_activate once with your key.

Spreadsheet update

Version 0.22.9 uses the vendor's patched SheetJS 0.20.3. Numeric date cells now follow the time actually stored in the workbook. Some numeric-date files produced by older versions can display 30 seconds differently in historical-offset timezones such as Ho Chi Minh. No guessed offset is added to your data. Reading does not rewrite the source file.

Tools

Resource template: sheet://<path> returns the sheet_info summary for that file. Resource: sheet://recent lists the files this server has opened since it started, most recent first (in memory only, nothing is written to disk, so the list is empty again after a restart).

Prompt: explore_sheet walks an unfamiliar file, sheet_info first, then concrete sheet_query calls built from the columns it actually found.

What you can say

Worked example

From docs/USER_VALUE_R2.md, a 400-row fixture with a title row and a blank row above the real header (row 3), sheets Sales / Reps / Notes, prices stored as strings like "1,516.16". One call, ground truth confirmed against the generator: Turing 650, Hopper 567, Linus T 551, Lovelace 486, Liskov 290.

You: Which rep sold the most units in the North region? Top 5 with totals.

  sheet_query {
    path: "/Users/you/sales.xlsx", sheet: "Sales",
    where: "[Region] = \"North\"",
    group_by: ["Rep"],
    aggregate: [{ col: "Units", fn: "sum", as: "total_units" }],
    sort: { col: "total_units", dir: "desc" },
    limit: 5
  }

Assistant: Query: where [Region] = "North"; group by Rep; sum Units as total_units;
sort total_units desc; limit 5
5 groups from 102 of 400 rows, showing 5

Alan Turing     650
Grace Hopper    567
Linus T         551
Ada Lovelace    486
Barbara Liskov  290

The response now echoes the exact query it ran (the Query: line) before the numbers, so a filter you did not ask for, an accidental AND [Status] = "Closed", say, is visible instead of silently narrowing the answer.

A second example, adding a column and saving without touching the source:

You: Add a Revenue column and save it as a CSV next to the original.

  sheet_add_column {
    path: "/Users/you/sales.xlsx", sheet: "Sales",
    name: "Revenue", formula: "[Units] * [Unit Price]",
    out_path: "/Users/you/sales.csv"
  }

Assistant: Wrote 400 rows (401 lines with header) to sales.csv.
Revenue = Units * Unit Price on every row, total 10,142,542.04.
Source file untouched.

The where and formula language

A small expression language, parsed and evaluated directly. There is no eval and no code execution: a bare word is always a column name, never a JavaScript value.

• Columns: [Unit Price] for names with spaces, Qty otherwise. Lookup is case insensitive.

• Comparisons: = != > >= < <= contains startswith endswith

• Logic: AND OR NOT and parentheses. AND binds tighter than OR.

• Arithmetic in formulas: + - * % / with the usual precedence.

• Strings: 'single' or "double" quotes; double a quote to escape it.

[Qty] >= 5 AND ([Status] = "open" OR [Region] contains "north")
[Amount] > 1000 AND NOT [Customer] startswith 'Test'

Formula example for sheet_add_column: [Qty] * [Unit Price]. When every column the formula reads holds at most 2 decimals, the result is rounded to 2 decimals, so [Amount] * 1.23 on money gives 40.79 rather than 40.7868. Pass decimals (0-10) to choose the precision yourself.

Numbers written as text in a CSV are converted by pattern, not by length: 1250.00, 12.00 and 1,250.00 all become numbers in the xlsx output, so Excel's own SUM counts them. Identifier-shaped and ambiguous values stay text: 007 keeps its leading zeros and 1.250,00 is left alone rather than guessed at.

Text comparisons ignore case and surrounding whitespace. Values like $1,250.00, 1 250, and 12% compare as numbers, so [Amount] > 1000 works on a column your spreadsheet stored as text.

Free vs Pro

Over a free read limit the tool still does the work and returns the part it is allowed to return (the first 5,000 rows), with a note saying what was left out. Over the free write limit nothing at all is written: a partial file that looks complete is worse than no file, so the tool refuses, tells you the row count and the cap, and suggests a free workaround (filter the rows down first, or write in 500-row batches). Nothing fails silently.

Get Pro

$19 one-time for this server, $39 for every server, lifetime: https://mcp.zovo.one/buy/spreadsheet

How it stores data

This server keeps no database of its own, it reads and writes the spreadsheet files you point it at, directly on your disk, and nothing else. Every write (sheet_write, sheet_add_column, sheet_convert in overwrite mode) goes to a temporary file in the same directory first, then is renamed into place, so an interrupted write leaves either the untouched original or the complete new file, never a truncated one. Because there is no shared state file, there is no advisory lock to take: two calls writing to two different output paths cannot collide, and a call to overwrite the same file twice in a row is simply two writes in sequence. To back up your data, back up the spreadsheet files themselves, there is nothing else to copy.

Limits and honest caveats

• Free reads cap at 5,000 rows and 5 MB; free writes cap at 500 rows per file and refuse rather than truncate, you get an error naming the row count and the cap, never a shorter file that looks complete.

• The hard ceiling is 50 MB regardless of tier; a file over that is refused outright with a clear message rather than risking memory exhaustion.

• The where/formula language is intentionally small: no regular expressions, no custom functions, no cross-sheet references in a single formula. It covers comparisons, boolean logic and arithmetic, nothing more.

• Writing an xlsx replaces one sheet, not the workbook. sheet_write with append or overwrite reads the whole workbook, swaps the sheet you named and writes every other sheet back, so Sheet2 and its data survive an append to Sheet1. What is not preserved is the sheet being written: it is rebuilt from values, so formulas, cell formatting, conditional formatting, charts, data validation and merged cells on that one sheet become plain values. Other sheets keep their cells as read. Take a copy first if the target sheet carries formatting you cannot recreate.

• Numbers written as text are read with locale-aware rules. 1,250.00, 1 250.00, $1,250.00, 12,99, 1.234,56 and EUR 1 250,00 all read as numbers; a decimal comma is only accepted in the unambiguous shape (a comma with exactly two digits at the end, dots or spaces grouping). Anything that mixes separators another way (1,2500.00) stays text rather than being guessed at. Values with leading zeros (007) and integers too large for exact arithmetic (over 9,007,199,254,740,991) stay text so they are never silently altered.

• Dates keep their cell type. A date cell read from an xlsx stays a date through queries and through a conversion back to xlsx. In text, CSV and JSON output it is rendered as ISO: 2026-09-04 for a date, 2026-09-03T15:30:00 when the cell carries a time.

• sheet_info's header-row guess is a heuristic (looks for the first row with lower emptiness and higher text density than the rows above it). It handles a title row and a blank row above the header; it is not proof against every layout, and you can always confirm what it picked before querying.

Troubleshooting

• npx hangs or fails to find the package: npm publish for this package is pending. Use the .mcpb bundle or the clone-and-build path above until it lands.

• Using the .mcpb bundle: it installs into Claude Desktop directly; there is no separate config step.

• Using the clone path: the server binary is servers/spreadsheet/dist/index.js after npm run build. Point your client's command at node with that absolute path as the only argument.

• Node version: requires Node >= 18. Check with node -v.

• "Path does not exist": the message includes the resolved absolute path (with ~ expanded), check it against where the file actually lives, especially inside a sandboxed or containerized client.

• A write is refused with a row-count message: you hit the free 500-row write cap. Filter the data down with sheet_query first, write in batches, or activate Pro.

• Nothing shows up / silent failures: logs go to stderr only, never stdout. In Claude Desktop check Settings -> Developer -> the server's log file; in Claude Code check the terminal or --mcp-debug.

Safety

• Paths that do not exist are refused with the resolved path in the message; ~ is expanded.

• Files over 50 MB are refused with a clear message rather than exhausting memory.

• sheet_add_column and sheet_convert write to a new file and refuse to clobber an existing one unless you pass out_path yourself.

• sheet_write with mode: "new_file" refuses to write over an existing file. Only mode: "overwrite" replaces file contents.

• Output files are written to a temporary name and renamed into place, so an interrupted write cannot truncate a file.

Privacy

All data stays local. Files are read from and written to your own disk, license keys are verified offline with an embedded public key, and the server makes no network requests at all.

Repeated checks on CSV exports

For a repeated CSV export workflow, the local CSV rule-check guide shows how to check additions, removals and maximum absolute price increases against one saved policy. Try the free browser demo before deciding whether the exact rules fit your files; your CSV data stays in that demo's browser and is not transferred from this MCP server.

The guide describes a separate proposed finite offline Node CLI pack at USD 7 once. No live checkout or preorder is available, and it is not part of this MCP server's Pro license. The free demo performs the same rule logic; the proposed paid benefit is a reusable local bundle and CLI workflow. It accepts only UTF-8 CSV with identical ordered headers and a single unique key, up to 1 MB and 5,000 rows per file. It does not import into a store or guarantee import safety.

Optional asynchronous workflow feedback can help identify repeated supported CSV checks, one-off uses, or inputs that need mapping first. Share only general workflow information; no CSV files, contact details, calls or payment are needed.

Pairs with

• mcp-time-tracker, export a CSV with export_csv, then query and reshape it here.

• mcp-invoice, pull line items out of a spreadsheet before turning them into an invoice.

• mcp-price-tracker, analyze exported price history as a sheet.

• office-suite, every sibling server behind one install, one config entry.

• Guide: Ask questions about an Excel or CSV file from Cursor or Claude

FAQ

Yes. sheet_info guesses the header row and reports which row it picked, so an export with a title line and a blank line above the real headers opens correctly without you specifying anything.

It groups. sheet_query takes group_by plus aggregate with sum, count, avg, min or max, and can sort by an aggregate alias, so top-N-by-category questions are a single call.

No, not unless you explicitly pass an output path that points at the source. sheet_add_column and sheet_convert write a new file next to the original by default.

Reads return the first 5,000 rows with a note naming what was omitted. Writes over 500 rows are refused outright rather than producing a truncated file, and the message tells you the row count, the cap and a free way round.

No. The server runs locally on your machine and reads your files directly. It makes no network requests, and it stores nothing of its own beyond the files you ask it to write.

Built by theluckystrike. Support: support@zovo.one

Use these docs as an MCP server

Any MCP client (Claude, Cursor, Windsurf, VS Code) can read this repository's documentation directly via GitMCP - no install:

• Docs MCP URL: https://gitmcp.io/theluckystrike/mcp-spreadsheet