xlvane: XLSX workbooks

io.github.DevXordPublished by GitHub account DevXordv1.3.3Updated Nov 5, 2026

XLSX tools: inspect, read, diff and validate workbooks; write, edit and convert with --allow-write.

VerifiedSTDIODesktop onlyFiles & StorageData & Analytics

Overview

AI-generated overview

Local MCP server for XLSX workbooks that lets an assistant inspect, read, diff and validate spreadsheets, and optionally write, edit or convert them.

What you can do
  • Inspect workbooks: sheets including hidden ones, used ranges, header rows, column types with samples, merged cells, formulas and warnings
  • Read sheet rows as objects keyed by the header row, with paging and ISO 8601 dates
  • Compare two workbooks cell by cell and validate column rules, reporting the cell of each problem
  • Write rows to a new XLSX file with a report preset, or set cells and append rows while keeping the rest unchanged
  • Convert XLSX to CSV, TSV or JSON and back, escaping formula-like text in CSV output
When to use it
Useful when an assistant needs to work with spreadsheet files on the local machine without writing code: reviewing a workbook's structure, extracting rows for analysis, checking two versions for differences, or producing and updating XLSX reports.
Requirements
Runs locally over stdio via npx from the npm package; needs Node.js 22 or later. At least one --root directory is required, and write tools appear only when started with --allow-write. Optional limits: --max-file-size, --max-rows, --max-response-chars, --max-cells. No accounts, API keys or environment variables.
Before you install
Write tools (write_table, edit_cells, convert) exist only with --allow-write and can create or replace files inside the roots; replacement needs overwrite set to true. Any file name inside a root may be written, including dot files, so choose roots carefully. edit_cells writes formulas as given and they are calculated only when a spreadsheet application opens the file. Workbook text is returned as data and may contain text meant to influence a model; macros are never run and external links are…

Installation

In SourceWeft

  1. Open xlvane: XLSX workbooks in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@xlvane/mcp

An MCP (Model Context Protocol) server for XLSX files, built on xlvane and the official MCP TypeScript SDK (@modelcontextprotocol/server 2.4.0, protocol revision 2026-07-28). An MCP client, such as a coding agent, can inspect, read, compare and validate workbooks, and optionally write, edit and convert them, through tools instead of code.

Requires Node.js 22 or later. Dependencies: xlvane and @modelcontextprotocol/server (which brings @modelcontextprotocol/core and zod).

Start

sh
npx @xlvane/mcp --root ./data                 # read-only, files inside ./datanpx @xlvane/mcp --root ./data --allow-write   # also write_table, edit_cells, convertxlvane mcp --root ./data                      # the same server, through the xlvane CLI

Many MCP clients take a configuration like this one; check your client's documentation for its exact format and file:

json
{  "mcpServers": {    "xlvane": { "command": "npx", "args": ["@xlvane/mcp", "--root", "/absolute/path/to/data"] }  }}
OptionMeaning
--root <dir>A directory the tools may use; repeat for several. Required. Relative paths in tool calls are resolved against the first one.
--allow-writeAlso offer the tools that write files. Without it they are not registered at all.
--max-file-size <bytes>Largest file read or written. Default 64 MiB.
--max-rows <n>Largest number of rows one read_table call returns. Default 1000.
--max-response-chars <n>Largest tool result (also an error), in characters of its JSON text; the message carries the same data again as structuredContent. read_table returns the rows that fit (truncated, nextOffset); other tools return XLV_E_LIMIT_EXCEEDED. Default 1 Mi (1 048 576).
--max-cells <n>Largest number of cells in a workbook a tool reads (the maxCells read limit). Default 5 000 000. Lower it when the server must answer quickly: diff holds both workbooks in memory.

The server speaks MCP over stdin and stdout; messages for people go to stderr.

Tools

ToolWritesWhat it does
inspect_workbooknoSheets (also hidden ones), used ranges, header rows, column types with samples, merged cells, formulas, warnings.
read_tablenoRows of a sheet as objects keyed by the header row; paging with offset and limit; dates as ISO 8601.
diffnoCell-by-cell differences between two workbooks.
validatenoRead warnings, and column rules (name, type, optional) with the cell of each problem.
write_tableyesRows to a new XLSX file (report preset: bold header, frozen row, autofilter, widths).
edit_cellsyesSet cells and append rows, keeping the rest of the file unchanged.
convertyesXLSX to CSV/TSV/JSON and back; CSV output escapes formula-like text.

Every tool has a JSON Schema for its input and returns its result as structuredContent and as JSON text. Errors are tool results with isError: true and the XlvError data: a stable code, the location, a hint and details (docs/errors.md).

Security

  • Directories: files are read and written only inside the --root directories. Paths are checked after symbolic links are resolved, so .., absolute paths and links that lead outside are refused (XLV_E_PATH_NOT_ALLOWED). A file is checked again after it is opened (the path must still lead to the same file), so swapping it for a link meanwhile does not help. Writing through a symbolic link is refused. A path outside the roots gets the same answer whether or not something exists there, also when it is reached through a symbolic link inside a root. Only regular files are read. Messages on stderr show control characters as \uXXXX.
  • Read-only by default: the write tools exist only with --allow-write. They create files exclusively and replace an existing file only when the call passes "overwrite": true, through a temporary file and a rename; the replacement keeps the file's permission bits (not setuid, setgid or sticky), and read-only files are not replaced. edit_cells writes formulas as given (for example HYPERLINK(...)); they are calculated when a spreadsheet application opens the file. Any file name inside a root may be written, also dot files such as .gitignore; choose the roots accordingly.
  • Limits: files above --max-file-size are refused for reading and writing (convert to JSON stops building the text at that size), workbooks above --max-cells cells are refused, and results above --max-response-chars are cut (read_table) or refused. The official MCP SDK closes the connection after a message larger than 10 MiB. The xlvane reader applies its limits for untrusted files (ZIP bombs, XML without DTDs or entities, the budgets of xlvane 1.1.1). validate lists at most 1 000 problems (problemsTotal counts all).
  • File content is data: values, sheet names and other text come from the files and may contain any text, also text meant to influence a model. The server returns it as data and does not interpret it.
  • No code execution: macros are never run, external links are never followed, and formulas are not calculated.

API

ts
import { createServer, runCli } from '@xlvane/mcp';

createServer({ roots, allowWrite, maxFileBytes, maxRows, maxResponseChars, maxCells, cwd }) returns an McpServer to connect to any transport; runCli(args) is the command line.

Links

License: MIT. The MCP SDK is licensed under Apache-2.0.

Source: packages/mcp/README.md at commit 3a56eb8

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the server did not start.

Version history

4
  1. v1.3.3LatestNov 5, 2026
  2. v1.3.2Nov 4, 2026
  3. v1.3.0Nov 4, 2026
  4. v1.2.2Nov 3, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts