@xlvane / mcp
为XLSX文件构建的MCP（模型上下文协议）服务器 xlvane 和官方MCP TypeScript SDK (@modelcontextprotocol/server 2.4.0，协议修订2026-07-28)。MCP客户端，比如编码代理，可以检查、读取、比较和验证工作簿，还可以选择通过工具而不是代码来编写、编辑和转换工作簿。
需要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> | 最大行数为1 read_table 调用返回。默认的1000。 |
--max-response-chars <n> | 最大的工具结果（也是一个错误），以其JSON文本的字符表示；消息再次携带相同的数据 structuredContent. read_table 返回符合(truncated， nextOffset）; 其他工具返回 XLV_E_LIMIT_EXCEEDED。默认1米（1 048 576）。 |
服务器通过标准输入和标准输出进行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 (文档/ errors.md)。
安全
- 目录: 文件只能在
--root目录。解析符号链接后检查路径，因此..，绝对路径和外部链接被拒绝(XLV_E_PATH_NOT_ALLOWED）. 打开文件后会再次检查文件（路径必须仍然指向相同的文件），因此同时将其交换为链接没有帮助。拒绝通过符号链接进行写入。根之外的路径得到的答案是一样的，不管那里是否有东西存在。只读取常规文件。 - 默认为只读： 写工具只存在于
--allow-write。它们专门创建文件，并仅在调用通过时替换现有文件"overwrite": true，通过临时文件和重命名；替换保留文件的权限，只读文件不被替换。可以写入根目录中的任何文件名，也可以写入点文件，例如.gitignore； 选择相应的根。 - 限制: 上面的文件
--max-file-size被拒绝阅读和写作，结果在上面--max-response-chars是吗？read_table)或拒绝。xlvane阅读器将其限制应用于不可信文件（ZIP炸弹、没有dtd或实体的XML、xlvane 1.1.1的预算）。validate最多列出1000个问题(problemsTotal计数)。 - 文件内容为data： 值、工作表名称和其他文本来自文件，可能包含任何文本，也包括旨在影响模型的文本。服务器将其作为数据返回，而不进行解释。
- 不执行代码： 永远不会运行宏，永远不会遵循外部链接，也不会计算公式。
API
import { createServer, runCli } from '@xlvane/mcp';
createServer({ roots, allowWrite, maxFileBytes, maxRows, maxResponseChars }) 返回一个 McpServer 连接：连接到任何运输工具； runCli(args) 是命令行。
链接
- 每个版本的变化： CHANGELOG.md
- bug和问题： GitHub的问题
- 报告漏洞： SECURITY.md
许可协议:麻省理工学院。MCP SDK是在Apache-2.0下授权的。