xlvane: XLSX workbooks

@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

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:

{  "mcpServers": {    "xlvane": { "command": "npx", "args": ["@xlvane/mcp", "--root", "/absolute/path/to/data"] }  }}

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

Tools

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

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

• Changes in each version: CHANGELOG.md
• Bugs and questions: GitHub issues
• Reporting a vulnerability: SECURITY.md

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