Xlvane MCP Server

xlvane

An MIT-licensed library for reading and writing XLSX files, designed for input from untrusted sources.

Releases are published from GitHub Actions with npm provenance: xlvane from 1.0.1, @xlvane/mcp from 1.2.2, and @xlvane/exceljs (named @xlvane/compat until 1.3.2, with provenance from 1.0.1) from its first release after 1.3.3, which is published from the maintainer's machine (SECURITY.md).

Website: xlvane.github.io (guide, error codes, an in-browser demo). Status: published on npm (xlvane, @xlvane/exceljs, @xlvane/mcp). Install with npm install xlvane (and npm install @xlvane/exceljs for the exceljs-compatible API). Changes for users are in CHANGELOG.md, planned and deferred work in ROADMAP.md; how releases are made is in docs/RELEASING.md.

Packages

Command line in 5 minutes

npm install -g xlvane                    # or use npx xlvane in a project
xlvane                                   # overview and common commands
xlvane inspect report.xlsx               # sheets, columns, header rows, warnings
xlvane read report.xlsx --sheet Sales    # print a sheet as a table
xlvane convert report.xlsx sales.csv     # XLSX ⇄ CSV / JSON
xlvane create data.json report.xlsx      # formatted report from JSON or CSV
xlvane diff old.xlsx new.xlsx            # what changed
xlvane help <command>                    # usage and examples

Add --json to any command for machine-readable output (docs/cli-json.md). More in packages/xlvane/README.md.

MCP server, Agent Skill and offline docs

• npx @xlvane/mcp --root ./data (or xlvane mcp --root ./data) serves the tools inspect_workbook, read_table, diff and validate for files inside ./data; --allow-write adds write_table, edit_cells and convert. See packages/mcp/README.md.
• skills/xlvane/SKILL.md is an Agent Skill with instructions and examples. Install it into a project with one command of the skills CLI: npx skills add ./node_modules/xlvane/skills --skill xlvane after npm install xlvane (works offline), or npx skills add <path-to-a-clone-of-this-repository>/skills --skill xlvane.
• The xlvane package also ships its documentation (docs/) and llms-full.txt (README, skill and docs in one file), so it is readable without network access.

Moving from exceljs or SheetJS

• docs/migrate-from-exceljs.md: switching a project from exceljs to @xlvane/exceljs with npx xlvane migrate and an npm alias, what to check afterwards and how to roll back.
• How to fix the CVEs in the xlsx package from npm: the two advisories of the xlsx (SheetJS) package on npm, the fixed SheetJS versions outside npm, and the equivalent xlvane calls.

xlvane compared with other libraries

Every cell below is backed by a recorded source (registry document, README or source file at a pinned version or commit), checked on 2026-11-03. Performance is not compared here.

What xlvane cannot do: it does not calculate formulas, does not open encrypted (password-protected) workbooks or legacy .xls files, does not model pivot tables, shapes, slicers or form controls, and reads and writes no format besides XLSX (plus XLSM, XLTX and XLTM on reading), CSV and JSON (packages/xlvane/README.md, SECURITY.md). @xlvane/exceljs is a replacement for the commonly used exceljs API; docs/exceljs-compat.md lists what is supported, partly supported and not supported. xlvane is an independent project, not affiliated with or endorsed by the authors of ExcelJS, SheetJS or excelize.

How xlvane is built and verified

• Who writes the code. The code, tests and documentation are written by AI coding agents (Claude Code), following the rules in CLAUDE.md and the maintainer's plan. Each phase starts with a plan that the maintainer approves; the maintainer also approves every release (staged publishing with two-factor authentication, docs/RELEASING.md). Decisions and checked facts, each with its source, are kept in the maintainer's internal notes, which are not in this repository.
• Tests. npm test ran 2200 tests in 203 files on 2026-11-03 (2149 passed, 48 skipped, 3 marked as to do; Node.js 22.23.4): unit tests, security tests (tests/security), policy tests (tests/policy: dependencies, release workflow, texts read by agents), command-line snapshots, the ported exceljs tests and the corpus tests.
• Corpus. 340 files of the Apache POI test corpus (Apache License 2.0; written by Excel for Windows, Mac and the web, LibreOffice, ONLYOFFICE and others, and damaged files) and files saved by LibreOffice; the origin and license of every file is in tests/corpus/LICENSES.md.
• Fuzzing. Property-based tests with fast-check in tests/fuzz. Each property runs XLV_FUZZ_RUNS times (100 in npm test, 20 000 by default in npm run fuzz; runs with XLV_FUZZ_RUNS=100000 are recorded for 1.1.1, for 1.2.2 before the 1.2.3 fixes and for 1.3.0), and the slower ones (CSV, sheet rules, edits, writing, streaming, streamed ZIP) a tenth to a fiftieth of that (tests/fuzz/runs.ts and the RUNS constant of each file).
• LibreOffice. tests/libreoffice opens files written by xlvane in LibreOffice Calc (headless) and checks the values, styles and layout it sees; CI installs LibreOffice and requires these tests.
• Runtimes. CI runs the tests on Node.js 22, 24 and 26, and the same smoke bundle in Bun, Deno, Chromium and workerd (Cloudflare Workers) (scripts/run-runtimes.mjs, .github/workflows/ci.yml).
• Security reviews. Independent reviews with proof-of-concept files were run before 1.1.1, on the published versions 1.0.0 to 1.2.2 before 1.2.3, and twice on the 1.3.0 release candidate. Each fixed finding has a test that failed before the fix.
• Provenance. Releases are built and published by .github/workflows/release.yml through npm trusted publishing, which adds provenance (xlvane from 1.0.1, @xlvane/mcp from 1.2.2, @xlvane/compat from 1.0.1 to 1.3.2; its successor @xlvane/exceljs from the first release after 1.3.3, which is published from the maintainer's machine).

Development

Requires Node.js 22.18+, 24.11+ or 26+ (the range supported by the build and test tools).

npm install
npm test            # unit, security, policy and corpus tests
npm run fuzz        # property-based tests with many runs
npm run typecheck   # TypeScript
npm run check:pkg   # build, publint, attw and package policy checks

How to report problems and propose changes is in CONTRIBUTING.md. Project rules are in CLAUDE.md, and the security policy in SECURITY.md.

License

MIT. @xlvane/exceljs is an independent project, not affiliated with or endorsed by the exceljs project or its authors; its LICENSE includes the exceljs MIT notice, because its API and type declarations follow exceljs 4.4.0.