sheets

mcp-spreadsheet

收录于 Awesome MCP Servers - 目录条目 | 在线托管端点，提供免费套餐，无需注册。

把电子表格交给 AI 助手，然后直接与它对话。将任意 .xlsx、.xlsm、.xlsb、.xls、.ods、.csv 或 .tsv 文件提供给它，再询问文件中的内容、筛选数据、计算新列，或另存为其他格式。它会帮你处理实际文件中那些棘手的问题：猜测哪一行是标题行，判断 CSV 使用逗号、分号还是制表符分隔，保留带引号的逗号和换行符，从 $1,250.00 格式的文本中读取数字，并报告每列的数据类型和空值数量。它绝不会修改原文件：每次写入都会保存到新路径，除非你明确选择 overwrite。数据不会离开本机，也无需获取 API 密钥。

已收录于官方 MCP Registry（io.github.theluckystrike/excel-spreadsheet-xlsx-csv）。

已列入 AI Product Index - 可通过 mcp.zovo.one/s/spreadsheet 使用在线远程端点，提供免费套餐，无需注册。

在聊天中读取、查询和扩展实际电子表格，全程无需触碰原文件。

60 秒安装

在 Claude Desktop 中使用 spreadsheet.mcpb v0.22.9。已发布的校验和和版本下载目录可用于确认准确的版本。npm 包尚未发布。

如需从源代码安装，请使用 Node.js 22 或更高版本，并先构建共享依赖项：

git clone https://github.com/theluckystrike/mcp-servers.git
cd mcp-servers
npm ci
node scripts/bootstrap-timezone.mjs
npm run build -w packages/mcp-license -w servers/spreadsheet

将此条目合并到 Claude Desktop 的 mcpServers，或合并到 Cursor 的 .cursor/mcp.json。将绝对路径替换为你的代码库路径：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["/absolute/path/mcp-servers/servers/spreadsheet/dist/index.js"]
    }
  }
}

Claude Code 的配置：

claude mcp add spreadsheet -- node /absolute/path/mcp-servers/servers/spreadsheet/dist/index.js

如需以 Pro 模式运行，请在同一配置块中设置 MCP_LICENSE_KEY，或使用你的密钥调用一次 license_activate。

电子表格更新

版本 0.22.9 使用供应商修补版 SheetJS 0.20.3。数值日期单元格现在会按照工作簿中实际存储的时间进行处理。由旧版本生成的某些数值日期文件，在胡志明市等使用历史时区偏移的地区可能会显示相差 30 秒。数据不会被添加任何推测出的偏移量。读取操作不会重写源文件。

工具

工具	功能
sheet_info	工作表名称、大小、推测的标题行、每列类型、示例值、空值计数
sheet_read	将行读取为文本表格、JSON 记录或 CSV；使用 limit/offset 分页，或指定 A1 range
sheet_query	使用 where 筛选，使用 group_by + aggregate（sum、count、avg、min、max）分组聚合，使用 select 选取列，使用 sort 排序（也支持聚合别名），并设置 limit
sheet_stats	逐列统计数量、空值、不同值、最小值、最大值、总和、平均值、中位数（文本列显示高频值）
sheet_find	在整个工作簿中查找文本；返回单元格地址和行预览
sheet_write	将行（对象或数组）写入新文件、追加到文件，或显式覆盖文件
sheet_add_column	根据公式添加计算列，并保存到新文件。数值结果会按输入值的精度取整（输入 2 位小数，输出 2 位小数）；可使用 decimals 覆盖
sheet_convert	将工作表转换为 csv、xlsx 或 json
license_status	查看是 Free 还是 Pro，以及如何升级
license_activate	激活 Pro 密钥（离线验证）

资源模板：sheet://<path> 返回该文件的 sheet_info 摘要。 资源：sheet://recent 列出此服务启动后打开的文件，按最近打开的顺序排列（仅保存在内存中，不会写入磁盘，因此重启后列表会再次变空）。

提示词：explore_sheet 会逐步探索不熟悉的文件，先调用 sheet_info，再根据实际找到的列构建具体的 sheet_query 调用。

你可以这样提问

你说	工具
“打开 sales.xlsx，告诉我里面有什么。”	sheet_info
“显示前 50 行。”	sheet_read
“北部地区哪位销售代表售出的单位数最多？列出前 5 名及总数。”	sheet_query（group_by + aggregate）
“Email 列有多少个空单元格，订单量中位数是多少？”	sheet_stats
“查找所有提到‘refund’的行。”	sheet_find
“将其写入名为 Q3 Results 的新工作表。”	sheet_write
“添加一个 Revenue 列，计算方式为 Units 乘以 Unit Price，并将其保存为与原文件同目录的 CSV。”	sheet_add_column
“将此 xlsx 转换为 JSON。”	sheet_convert
“我使用的是免费版还是 Pro？”	license_status
“这是我的许可证密钥，请激活。”	license_activate

操作示例

示例取自 docs/USER_VALUE_R2.md：一个含 400 行的数据文件，顶部有标题行，真实表头上方还有一个空行 （第 3 行），包含 Sales / Reps / Notes 工作表，价格以 "1,516.16" 这样的字符串存储。调用一次后，结果与生成器确认的基准答案一致：Turing 650、Hopper 567、Linus T 551、Lovelace 486、Liskov 290。

You: Which rep sold the most units in the North region? Top 5 with totals.

  sheet_query {
    path: "/Users/you/sales.xlsx", sheet: "Sales",
    where: "[Region] = \"North\"",
    group_by: ["Rep"],
    aggregate: [{ col: "Units", fn: "sum", as: "total_units" }],
    sort: { col: "total_units", dir: "desc" },
    limit: 5
  }

Assistant: Query: where [Region] = "North"; group by Rep; sum Units as total_units;
sort total_units desc; limit 5
5 groups from 102 of 400 rows, showing 5

Alan Turing     650
Grace Hopper    567
Linus T         551
Ada Lovelace    486
Barbara Liskov  290

现在，响应会在数字前回显实际运行的确切查询（Query: 行），因此，未请求的筛选条件（例如意外加入 AND [Status] = "Closed"）会清晰显示，而不会悄悄缩小答案范围。

另一个示例：添加列并保存，同时不触碰源文件：

You: Add a Revenue column and save it as a CSV next to the original.

  sheet_add_column {
    path: "/Users/you/sales.xlsx", sheet: "Sales",
    name: "Revenue", formula: "[Units] * [Unit Price]",
    out_path: "/Users/you/sales.csv"
  }

Assistant: Wrote 400 rows (401 lines with header) to sales.csv.
Revenue = Units * Unit Price on every row, total 10,142,542.04.
Source file untouched.

where 和 formula 语言

一种小型表达式语言，可直接解析和求值。它不使用 eval，也不执行代码：裸词始终是列名，而不是 JavaScript 值。

• 列：名称中带空格时使用 [Unit Price]，否则使用 Qty。查找时不区分大小写。
• 比较：= != > >= < <= contains startswith endswith
• 逻辑：AND OR NOT 和括号。AND 的优先级高于 OR。
• 公式中的算术：+ - * % /，遵循常规优先级。
• 字符串：使用 '单引号' 或 "双引号"；重复输入引号即可转义。

[Qty] >= 5 AND ([Status] = "open" OR [Region] contains "north")
[Amount] > 1000 AND NOT [Customer] startswith 'Test'

sheet_add_column 的公式示例：[Qty] * [Unit Price]。当公式读取的每一列最多包含 2 位小数时，结果会四舍五入到 2 位小数，因此对金额使用 [Amount] * 1.23 会得到 40.79，而不是 40.7868。传入 decimals（0-10）可自行选择精度。

CSV 中以文本形式写入的数字会按模式转换，而不是按长度转换：1250.00、12.00 和 1,250.00 在 xlsx 输出中都会转换为数字，因此 Excel 自带的 SUM 会将它们计入。形似标识符或含义不明确的值仍会保留为文本：007 会保留前导零，而 1.250,00 会原样保留，不会被擅自猜测。

文本比较会忽略大小写和前后空格。像 $1,250.00、1 250 和 12% 这样的值会按数字进行比较，因此 [Amount] > 1000 可用于电子表格中以文本形式存储的列。

免费版与 Pro

	免费版	Pro
所有读取文件的工具（sheet_info、sheet_read、sheet_query、sheet_stats、sheet_find、sheet_add_column、sheet_convert）	文件最大为 5 MB，最多 5,000 行	无限制（文件大小上限为 50 MB）
sheet_write、sheet_add_column、sheet_convert	每个文件最多写入 500 行；超过时不会写入任何内容，工具会说明原因	无限制
工作表、格式、表达式语言	全部可用	全部可用

超过免费读取限制时，工具仍会执行操作并返回允许返回的部分（前 5,000 行），同时说明省略了哪些内容。超过免费写入限制时，不会写入任何内容：看似完整的部分文件比没有文件更糟，因此工具会拒绝操作，告知行数和上限，并建议免费的解决方法（先筛选行，或分批写入，每批 500 行）。所有失败都会明确告知，不会悄无声息地失败。

获取 Pro

此服务一次性付费 $19，所有服务一次性付费 $39，终身有效：https://mcp.zovo.one/buy/spreadsheet

数据存储方式

此服务不保留自己的数据库，而是直接在你的磁盘上读取和写入你指定的电子表格文件，不会进行其他操作。每次写入（sheet_write、sheet_add_column、sheet_convert 的 overwrite 模式）都会先写入同一目录下的临时文件，再将其重命名到目标位置，因此即使写入中断，留下的也只会是未改动的原文件或完整的新文件，绝不会是被截断的文件。由于没有共享状态文件，因此无需获取咨询锁：写入两个不同输出路径的两次调用不会冲突，而连续两次调用 overwrite 同一文件则只是按顺序执行两次写入。要备份数据，只需备份电子表格文件本身，无需复制其他内容。

限制与如实说明

• 免费读取上限为 5,000 行和 5 MB；免费写入每个文件上限为 500 行，并且会拒绝操作，而不是截断数据。你会收到一条指出行数和上限的错误消息，绝不会得到一个看似完整的较短文件。
• 无论套餐等级如何，硬性上限都是 50 MB；超过此上限的文件会被直接拒绝，并显示明确消息，以免耗尽内存。
• where/formula 语言有意保持精简：不支持正则表达式、自定义函数，也不支持在单个公式中跨工作表引用。它仅支持比较、布尔逻辑和算术运算，不支持其他功能。
• 写入 xlsx 会替换一个工作表，而不是整个工作簿。 sheet_write 使用 append 或 overwrite 时，会读取整个工作簿，替换你指定的工作表，并写回其他所有工作表，因此向 Sheet1 追加数据时，Sheet2 及其数据会保留。但不会保留正在写入的工作表：该工作表会根据值重新构建，因此其中的公式、单元格格式、条件格式、图表、数据验证和合并单元格都会变为纯值。如果目标工作表包含无法重新创建的格式，请先备份。
• 以文本形式写入的数字会按照区域格式规则读取。 1,250.00、1 250.00、$1,250.00、12,99、1.234,56 和 EUR 1 250,00 都会读取为数字；只有格式明确时才接受小数逗号（末尾恰好有两位数字，整数部分以点或空格分组）。以其他方式混用分隔符的值（1,2500.00）会保留为文本，不会进行猜测。带前导零的值（007）以及大到无法精确运算的整数（超过 9,007,199,254,740,991）会保留为文本，因此绝不会被悄悄改动。
• 日期会保留其单元格类型。 从 xlsx 读取的日期单元格在查询过程中以及转换回 xlsx 时都会保留为日期。在文本、CSV 和 JSON 输出中，日期会呈现为 ISO 格式：日期为 2026-09-04；单元格包含时间时为 2026-09-03T15:30:00。
• sheet_info 对标题行的判断是启发式的（会查找首个空白程度低于上方行且文本密度高于上方行的行）。它能处理标题行和标题上方的空白行，但无法保证适用于所有布局；你可以在查询前随时确认它选中了哪一行。

故障排除

• npx 卡住或无法找到软件包：此软件包仍待发布到 npm。在发布前，请使用 .mcpb 安装包或上文的克隆并构建方式。
• 使用 .mcpb 安装包：它会直接安装到 Claude Desktop；无需单独配置。
• 使用克隆方式：运行 npm run build 后，服务二进制文件位于 servers/spreadsheet/dist/index.js。将客户端的 command 指向 node，并将该绝对路径作为唯一参数。
• Node 版本：需要 Node >= 18。使用 node -v 检查。
• “Path does not exist”：消息中会包含解析后的绝对路径（已展开 ~），请核对该路径与文件实际位置是否一致，尤其是在沙盒化或容器化的客户端中。
• 写入因行数提示而被拒绝：你已达到免费写入 500 行的上限。请先用 sheet_query 筛选数据，分批写入，或启用 Pro。
• 没有显示内容／静默失败：日志仅写入 stderr，绝不会写入 stdout。在 Claude Desktop 中，查看“Settings -> Developer”下该服务的日志文件；在 Claude Code 中，查看终端或 --mcp-debug。

安全性

• 不存在的路径会被拒绝，并在消息中显示解析后的路径；~ 会展开。
• 超过 50 MB 的文件会被拒绝，并给出清晰的提示，而不会导致内存耗尽。
• sheet_add_column 和 sheet_convert 会写入新文件；除非你自行传入 out_path，否则不会覆盖已有文件。
• sheet_write 使用 mode: "new_file" 时，若文件已存在，则会拒绝写入。只有 mode: "overwrite" 会替换文件内容。
• 输出文件会先写入临时文件名，再重命名到目标位置，因此即使写入中断，也不会截断文件。

隐私

所有数据都保留在本地。文件从你的磁盘读取并写入你的磁盘；许可证密钥通过内嵌公钥离线验证；服务完全不会发出网络请求。

重复检查 CSV 导出文件

对于重复的 CSV 导出工作流，本地 CSV 规则检查指南介绍了如何根据一项已保存的策略检查新增项、移除项和价格最大绝对涨幅。在决定这些具体规则是否适用于你的文件之前，可以试用免费的浏览器演示；你的 CSV 数据会保留在该演示所在的浏览器中，不会从此 MCP 服务传出。

该指南介绍的是一个单次收费 7 美元、独立且拟议中的离线 Node 命令行工具包。目前没有在线结账或预购服务，它也不属于此 MCP 服务的 Pro 许可证。免费演示会执行相同的规则逻辑；拟议中的付费权益是可重复使用的本地工具包和命令行工作流。它只接受 UTF-8 CSV，且文件的表头顺序必须完全一致，并且只能有一个唯一键；每个文件最多 1 MB、5,000 行。它不会导入到商店，也不保证导入安全。

可选的异步工作流反馈有助于识别重复使用的受支持 CSV 检查、一次性用途，或需要先进行映射的输入。请只分享一般性的工作流信息；无需提供 CSV 文件或联系方式，也无需通话或付款。

可搭配使用

• mcp-time-tracker：使用 export_csv 导出 CSV，然后在这里查询并调整其结构。
• mcp-invoice：从电子表格中提取行项目，然后将其转换为发票。
• mcp-price-tracker：将导出的价格历史记录作为表格进行分析。
• office-suite：一次安装、一个配置项，即可使用所有同系列服务。
• 指南：在 Cursor 或 Claude 中询问 Excel 或 CSV 文件

常见问题

可以。sheet_info 会猜测表头所在行，并报告所选的行号；因此，即使导出文件的真实表头上方有标题行和空行，也无需指定任何内容即可正确打开。

支持分组。sheet_query 接受 group_by，并支持使用 sum、count、avg、min 或 max 进行 aggregate，还可以按聚合别名排序，因此只需一次调用即可查询各类别的前 N 项。

不会，除非你明确传入一个指向源文件的输出路径。默认情况下，sheet_add_column 和 sheet_convert 会在原文件旁边写入新文件。

读取时会返回前 5,000 行，并说明省略了哪些内容。写入超过 500 行的内容会直接被拒绝，而不会生成截断文件；消息会告知行数、上限以及一种免费解决方法。

不会。服务在你的设备上本地运行，并直接读取你的文件。它不会发出网络请求，也不会存储任何自身数据，只有你要求它写入的文件除外。

由 theluckystrike 构建。支持邮箱：[email protected]

将这些文档用作 MCP 服务

任何 MCP 客户端（Claude、Cursor、Windsurf、VS Code）都可以通过 GitMCP 直接读取此仓库的文档，无需安装：

• 文档 MCP URL：https://gitmcp.io/theluckystrike/mcp-spreadsheet