All servers / Files / SheetXL MCP server
SheetXL MCP server
MCP server for SheetXL, an Excel-grade spreadsheet built for agents and developers. Read, query, build and check .xlsx, .sxl and .csv files.
Tested by ConnectATDScore 90 out of 100. Tested 2026-11-18 on package version 1.0.6. Package: @sheetxl/mcp · source
Score breakdown
| Runs | 18 / 20 | |
|---|---|---|
| Tool descriptions | 20 / 20 | |
| Package safety | 20 / 20 | |
| Maintenance | 20 / 20 | |
| Adoption | 12 / 20 |
What we saw
- Starts and answers the MCP handshake: yes (4.2 seconds including download)
- Tools offered: 14
- Last published: 2026-11-18
- Weekly downloads (npm): 1,899
- License: SEE LICENSE IN LICENSE.md · Direct dependencies: 6
Want this server set up for your team?
ConnectATD builds AI automation and wires up MCP servers like this one. Tell us what you are trying to do.
Talk to ConnectATDTools and how they are described
Agents choose tools from these descriptions. Under each name you can see how many of its parameters are explained.
infono parametersREQUIRED first call. One read-only report that settles both questions you must answer before touching a workbook: whether the engine is ready here (version, type definitions, reference documents, license) and whether a HUMAN IS WATCHING. A `attended` session means a user has that workbook open RIGHT NOW — unqualified references ("B10") mean that workbook, reach it only through its session, and never go find a file on disk. Anything missing or stale comes back with the exact command to fix it. Use `list_sessions` afterwards to re-check presence without repeating the full report.
list_sessionsno parametersLists all open sessions: sandboxes owned by this server (headless) plus attended workbooks open in VS Code. `info` already includes this — reach for `list_sessions` to RE-CHECK presence mid-task (has the user opened or closed something?) without paying for the full readiness report. A `attended` session means a user has that workbook open RIGHT NOW. Each entry has an id, kind (sandbox|attended), origin, whether a grid is showing it (view| headless), its file, and current head commit; session_ids route every other tool. Also lists RECENTLY CLOSED sessions — including a workbook the editor reopened under a new id, which is what to use when an id you were holding stops working. You rarely need to poll this: attended-session changes (the user opened, closed, or reloaded a workbook in the editor) are announced automatically at the top of your next tool result.
session_create4 of 4 parameters describedCreate a new server-owned sandbox session (headless, in-process). With no arguments it is an empty workbook; `path` opens a workbook from disk; `source` clones another session (its workbook is snapshotted into a fresh sandbox you can edit in isolation). Returns the new session_id to pass to run/grep/etc.
session_close1 of 1 parameter describedClose (dispose) a sandbox session, freeing its in-memory workbook. Only sandboxes can be closed — attended (VS Code) sessions are owned by the UI and cannot be closed here.
run7 of 7 parameters describedExecute SDK TypeScript against a session as one undoable commit — the write path AND every structured read. Source arrives as `code` (a string) or `path` (a file); what it MEANS is decided by the code itself. No default export = a SNIPPET: the run context (`wb`, `log`, `warn`, `error`, `args`) is ambient, async is implicit (never write `await`), and the final expression is the result. A default export = a SCRIPT handed that context; its return value is the result. RETURNING A SUBJECT DESCRIBES IT: `{ code: "wb" }` renders the workbook report, `wb.getWorksheet('Sales').getRegions()` maps the uniform blocks, `wb.getRange('Sales!B2:D9').getStats()` the numbers — ask for the answer, not the cells. There is no query tool: every structured question is one line of `run`. Returns status "ok", "compile_error" (fix the source, call again), "runtime_error", or "drift" (the session changed since `original_commit_id` — re-read and retry). On success use `commitId` with `session_revert`.
session_revert2 of 2 parameters describedUndo a specific change by its commitId (from `run`).
list_commits2 of 2 parameters describedThe session's commit log, newest first — the ids `session_revert`/`session_restore` take. Each entry carries a description, who wrote it (unattributed when nothing recorded that), and a timestamp, in the order the changes happened. Reach for it when the session predates your context, or to see whether things changed mid-task (commits you did not write, and where they fall among yours).
session_restore2 of 2 parameters describedRestore the session to a previous commit point by commitId.
grep12 of 12 parameters describedSearch a workbook's text by pattern: cell contents, and the text that is in no cell — comments, shapes, charts and defined names. Returns grid-anchored matches, each tagged with the layer it matched. Selection by attribute (fills, formats, features) is the regions read, not grep.
api1 of 1 parameter describedLook up the scripting API — what you can call on a type, without reading the type definitions. `ICellRange` lists its members, one line each (signature + summary); `ICellRange.setValues` prints that member's full documentation; any other word searches type and member names; no name lists where to start. Answers come from the same declarations `run` type-checks against, so a member listed here exists.
session_save3 of 3 parameters describedSave a session's workbook to disk. Without `path`, or with the session's own file, it is a Save back to that file. Any other `path` is a Save As: a sandbox session then belongs to the new file; an attended session writes a copy and stays on its own file. The file extension picks the format — prefer `.sxl` for working copies and pipelines, `.xlsx` when Excel itself will open the file. Relative paths resolve against the workspace. A Save As refuses to replace an existing file unless `overwrite` is true.
highlight3 of 3 parameters describedMark ranges in a session's grid so the user can SEE them — a list of findings they can walk, or where you are working right now. Ephemeral, never a commit, and it asks NOTHING: nobody has to respond, and the user may clear it whenever they like. To ask a question instead, use `prompt`. THE ORDER OF `ranges` IS THE ORDER THE USER WALKS THEM — rank a findings list most important first rather than in scan order. A `finding` or `question` call ADDS a list the user reviews, which stays until they dismiss it. `working` is your cursor — ONE range, where you are about to write: it replaces your prior `working` mark and clears itself when the workbook next changes or you highlight anything else; the user never manages it. An empty `ranges` array clears the given intent only. Only sessions with a UI view can show anything; on a headless sandbox this reports that nothing was marked. Brings the first range into view but never moves the user's selection — the selection is theirs.
screenshot5 of 5 parameters describedSee a range as an image: SheetXL renders the session's current workbook in a headless Chrome or Edge and returns a PNG — values as formatted, fills, fonts, borders, column widths, `#####` where a value does not fit, the saved selection. Use it to check what a person would see, above all after formatting or building a chart; the read tools remain the way to learn values and formulas. Headers are on by default so you can map the picture back to A1. A range larger than `max_edge` is cut at the last whole row or column and the result says where. This is a render of the workbook, not of the user's window: it does not show their scroll position or unsaved edits in a cell editor. On a machine without Chrome or Edge it says so and nothing else changes.
prompt5 of 5 parameters describedAsk the user in the spreadsheet grid and wait for their answer — use it when the work cannot proceed without a decision that is genuinely theirs. One question: pass `message` (and `options`, `range`). Several related decisions: pass `questions` instead — they are shown as steps of ONE dialog, each at its own cells, and answered together. Returns the chosen option id(s), or cancel (with any answers given before it). A question with options also lets the user answer in their own words ("Other"); that answer comes back as text instead of an id. ONE prompt at a time per session: while one is waiting on the user another is refused — wait for the answer or cancel that task. Pass `range` when a question is ABOUT specific cells and it is shown at them, which is most of the time; without one it is a centred dialog. To show cells WITHOUT asking anything — a findings list, a running narration — use `highlight` instead; it expects no response. Requires a session with a UI view (a workbook open in the client). On clients with task support the call returns immediately and you poll the task; on clients without it, the call blocks until the user responds. FALLBACK: if it errors because no UI session is available, ask the user the question directly in chat and proceed on their reply.
Tested in a sandbox with an empty environment: no API keys, a throwaway folder, nothing from a real account. A passing test shows the server runs and responds. It is not a security audit.