xlvane: XLSX workbooks

@xlvane/mcp

一个 MCP 服务，允许客户端检查、读取、写入、编辑、转换、比较和验证 XLSX 文件，且仅限于启动时指定的目录。

文档：xlvane.github.io/guide/mcp.html。

一个用于处理 XLSX 文件的 MCP（Model Context Protocol）服务，基于 xlvane 和官方 MCP TypeScript SDK（@modelcontextprotocol/server 2.4.0，协议修订版 2026-07-28）构建。MCP 客户端（例如编码 Agent）可以通过工具而非代码检查、读取、比较和验证工作簿，并可选择写入、编辑和转换工作簿。

需要 Node.js 22 或更高版本。依赖项：xlvane 和 @modelcontextprotocol/server（后者会引入 @modelcontextprotocol/core 和 zod）。

启动

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

许多 MCP 客户端接受类似这样的配置；具体格式和文件请查看客户端文档：

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

选项	含义
--root <dir>	工具可以使用的目录；可重复指定多个目录。必填。工具调用中的相对路径以第一个目录为基准解析。
--allow-write	同时提供用于写入文件的工具。不启用此选项时，这些工具不会注册。
--max-file-size <bytes>	读取或写入的最大文件大小。默认值为 64 MiB。
--max-rows <n>	单次 read_table 调用返回的最大行数。默认值为 1000。
--max-response-chars <n>	最大工具结果大小（错误也计入），以 JSON 文本中的字符数计；消息会在 structuredContent 中再次携带相同数据。read_table 会返回符合大小限制的行（truncated、nextOffset）；其他工具会返回 XLV_E_LIMIT_EXCEEDED。默认值为 1 Mi（1 048 576）。
--max-cells <n>	工具读取的工作簿中的最大单元格数（即 maxCells 读取限制）。默认值为 5 000 000。若需服务快速响应，请调低此值：diff 会将两个工作簿都载入内存。

该服务通过 stdin 和 stdout 使用 MCP 通信；面向用户的消息会发送到 stderr。

工具

工具	写入	功能
inspect_workbook	否	工作表（包括隐藏的工作表）、使用范围、标题行、带样例的列类型、合并单元格、公式和警告。
read_table	否	将工作表的行作为以标题行为键的对象返回；支持使用 offset 和 limit 分页；日期采用 ISO 8601 格式。
diff	否	比较两个工作簿中逐个单元格的差异。
validate	否	读取警告和列规则（name、type、optional），并标出每个问题所在的单元格。
write_table	是	将行写入新的 XLSX 文件（报告预设：粗体标题、冻结行、自动筛选、列宽）。
edit_cells	是	设置单元格并追加行，同时保持文件其余部分不变。
convert	是	在 XLSX 与 CSV/TSV/JSON 之间相互转换；CSV 输出会转义类似公式的文本。

每个工具都有描述其输入的 JSON Schema，并将结果作为 structuredContent 和 JSON 文本返回。错误会作为工具结果返回，包含 isError: true 和 XlvError 数据：稳定的 code、location、hint 和 details（docs/errors.md）。

安全性

• 目录： 仅在 --root 目录内读取和写入文件。解析符号链接后会检查路径，因此会拒绝 ..、绝对路径以及指向外部的链接（XLV_E_PATH_NOT_ALLOWED）。文件打开后还会再次检查（路径必须仍指向同一文件），因此期间将其替换为链接也无济于事。拒绝通过符号链接写入。无论路径外是否存在文件，都会得到相同的响应；即使通过根目录内的符号链接访问也是如此。仅读取常规文件。stderr 上的消息会将控制字符显示为 \uXXXX。
• 默认只读： 只有使用 --allow-write 时才会提供写入工具。工具会以独占方式创建文件，且仅当调用传入 "overwrite": true 时才会通过临时文件和重命名替换现有文件；替换后的文件会保留其权限位（不包括 setuid、setgid 或 sticky），只读文件不会被替换。edit_cells 会按原样写入公式（例如 HYPERLINK(...)）；这些公式会在电子表格应用打开文件时计算。根目录内的任何文件名都可以写入，包括 .gitignore 等点文件；请据此选择根目录。
• 限制： 拒绝读取或写入超过 --max-file-size 的文件（将 convert 转换为 JSON 时，会在达到该大小后停止构建文本）；拒绝处理超过 --max-cells 个单元格的工作簿；超过 --max-response-chars 的结果会被截断（read_table）或拒绝。官方 MCP SDK 会在消息超过 10 MiB 后关闭连接。xlvane 读取器会对不可信文件应用其限制（ZIP 炸弹、无 DTD 或实体的 XML，以及 xlvane 1.1.1 的预算限制）。validate 最多列出 1 000 个问题（problemsTotal 统计所有问题）。
• 文件内容是数据： 值、工作表名称和其他文本都来自文件，可能包含任何文本，包括意图影响模型的文本。服务会将其作为数据返回，不会对其进行解释。
• 不执行代码： 不会运行宏，不会跟随外部链接，也不会计算公式。

API

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

createServer({ roots, allowWrite, maxFileBytes, maxRows, maxResponseChars, maxCells, cwd }) 会返回一个可连接到任意传输方式的 McpServer；runCli(args) 是命令行。

商标

本文档中的 Node.js、GitHub、npm、Model Context Protocol 及其他名称均归其各自所有者所有。xlvane 是一个独立项目，与这些名称的所有者均无关联，也未获其认可。

链接

• 各版本的变更：CHANGELOG.md
• 问题与疑问：GitHub issues
• 报告漏洞：SECURITY.md

许可证：MIT。MCP SDK 采用 Apache-2.0 许可证。