xlvane: XLSX workbooks

@xlvane/mcp

An MCP server that lets a client inspect, read, write, edit, convert, compare and validate XLSX files, limited to the directories given at start.

Documentation: xlvane.github.io/guide/mcp.html.

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 ./data

npx @xlvane/mcp --root ./data --allow-write # also write_table, edit_cells, convert xlvane 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.

Trademarks

Node.js, GitHub, npm, the Model Context Protocol and the other names in this document belong to their owners. xlvane is an independent project and is not affiliated with or endorsed by any of them.

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.