An MCP server that lets an AI client inspect, read, write, edit, convert, compare, and validate XLSX files within specified directories.
Also known as DevXord/xlvane, xlvane, @xlvane/mcp
- Stars
- 0
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- 1.3.4
- Last commit
- Nov 12, 2026
- License
- MIT
What is xlvane MCP?
xlvane is an MCP server that lets an AI client inspect, read, write, edit, convert, compare, and validate XLSX files within specified directories. It exposes 4 tools, such as inspect_workbook, read_table, diff.
Summary generated from the project's README
About xlvane MCP server
Managing spreadsheet data directly from an AI client is what this MCP server enables for developers and data analysts. It provides a set of tools to inspect, read, compare, and validate XLSX workbooks within specific directories. By connecting through an MCP client like a coding agent, users can perform complex spreadsheet operations without writing custom parsing code.
The server operates locally using Node.js 22 or later and requires a designated root directory to ensure security. By default, the server runs in a read-only mode, but users can enable writing, editing, and conversion capabilities by adding the allow-write flag. It includes specific controls for handling large datasets, such as setting limits on file size, row counts, and the total number of cells processed.
Key tools include inspect_workbook for analyzing sheet structures and formulas, diff for finding cell-by-cell differences between files, and validate for checking column rules. For data manipulation, the server offers write_table to create new files, edit_cells to modify existing ones, and convert to switch between XLSX, CSV, TSV, and JSON formats.
Written from the project's README. Every use case is checked against a quote from it.
How to install xlvane MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall xlvane MCP in Claude Code
$ claude mcp add xlvane -- npx -y @xlvane/mcp --root /path/to/folderInstall xlvane MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"xlvane": {
"command": "npx",
"args": [
"-y",
"@xlvane/mcp",
"--root",
"/path/to/folder"
]
}
}
}Install xlvane MCP in VS Code
.vscode/mcp.json
{
"servers": {
"xlvane": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@xlvane/mcp",
"--root",
"/path/to/folder"
]
}
}
}Install xlvane MCP in VS Code CLI
$ code --add-mcp '{"name":"xlvane","type":"stdio","command":"npx","args":["-y","@xlvane/mcp","--root","/path/to/folder"]}'Install xlvane MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"xlvane": {
"command": "npx",
"args": [
"-y",
"@xlvane/mcp",
"--root",
"/path/to/folder"
]
}
}
}Install xlvane MCP in Codex
$ codex mcp add xlvane -- npx -y @xlvane/mcp --root /path/to/folderInstall xlvane MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.xlvane] command = "npx" args = ["-y", "@xlvane/mcp", "--root", "/path/to/folder"]
Install xlvane MCP in Gemini CLI
$ gemini mcp add -s user xlvane npx -- -y @xlvane/mcp --root /path/to/folderInstall xlvane MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"xlvane": {
"command": "npx",
"args": [
"-y",
"@xlvane/mcp",
"--root",
"/path/to/folder"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @xlvane/mcp 1.3.4 in an isolated container with no network and no keys. It answered and listed 4 tools.
xlvane MCP tools 4
Read from the server with tools/listinspect_workbookRead-onlyDescribes an XLSX file without changing it: sheets (including hidden ones), used ranges, detected header rows, column types with sample values, merged cells, example formulas, pictures and charts (position, chart types, title, series count), and warnings (macros, external links, damaged parts). Macros are never run and links are never followed. Use it before read_table to find the sheet and header row.
read_tableRead-onlyReads a sheet as an array of row objects keyed by the header row (or by column letters with header: false). Dates are returned as ISO 8601 strings in UTC, error cells as their code (e.g. "#N/A"), formulas as their cached result. Returns at most 1000 rows per call; use offset to page through larger sheets (totalRows and truncated say whether more rows exist).
diffRead-onlyCompares two XLSX files cell by cell (values and formulas; formatting with styles: true). Sheets are matched by name. Use it to check the result of an edit.
validateRead-onlyReports read warnings of an XLSX file and, with columns, checks a table: each listed column must exist in the header row, its cells must not be empty unless optional is true, and must have the given type. Each problem names the cell. ok is false when problems were found (warnings count only with strict: true).
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledevxord/xlvane is public and reachablegithub.com/devxord/xlvane ↗Pass
- Package names this repository as its source@xlvane/mcp names devxord/xlvane as sourcenpmjs.com/package/@xlvane/mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @xlvane/mcpnpmjs.com/package/@xlvane/mcp/v/1.3.4#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/devxord/xlvane ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @xlvane/mcpPass
- No critical advisory in the package or its dependencies6 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model7 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@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"] }
}
}
| Option | Meaning |
|---|---|
--root <dir> |
A directory the tools may use; repeat for several. Required. Relative paths in tool calls are resolved against the first one. |
--allow-write |
Also 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
| Tool | Writes | What it does |
|---|---|---|
inspect_workbook |
no | Sheets (also hidden ones), used ranges, header rows, column types with samples, merged cells, formulas, warnings. |
read_table |
no | Rows of a sheet as objects keyed by the header row; paging with offset and limit; dates as ISO 8601. |
diff |
no | Cell-by-cell differences between two workbooks. |
validate |
no | Read warnings, and column rules (name, type, optional) with the cell of each problem. |
write_table |
yes | Rows to a new XLSX file (report preset: bold header, frozen row, autofilter, widths). |
edit_cells |
yes | Set cells and append rows, keeping the rest of the file unchanged. |
convert |
yes | XLSX 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
--rootdirectories. 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_cellswrites formulas as given (for exampleHYPERLINK(...)); 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-sizeare refused for reading and writing (convertto JSON stops building the text at that size), workbooks above--max-cellscells are refused, and results above--max-response-charsare 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).validatelists at most 1 000 problems (problemsTotalcounts 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.
xlvane MCP questions
How do I add xlvane MCP to Claude Code?
Run claude mcp add xlvane -- npx -y @xlvane/mcp --root /path/to/folder in your terminal. Add --scope user to make it available in every project.
How do I add xlvane MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does xlvane MCP provide?
It exposes 4 tools, including inspect_workbook, read_table, diff, validate.
Is there a limit to the file size I can process?
Yes, you can configure the --max-file-size option, which defaults to 64 MiB.
How does the server handle security and directory access?
The server only reads and writes files within the directories specified by the --root argument and prevents access to paths outside those roots.
Does the server execute macros or formulas?
No, the server does not run macros, follow external links, or calculate formulas.