KitchenSink4XL

KitchenSink4XL

使用 AI 助手读取和编辑 Excel 工作簿，并了解每个公式结果是最新计算的、缓存的还是缺失的。

AI 可在 Excel 中执行 131 项操作，每次更改前都会备份，每次保存后都会检查。

KitchenSink4XL 是一个 MCP 服务，可让 Claude Code、Codex CLI、Copilot CLI、Claude Desktop 和其他本地 MCP 客户端处理 .xlsx 和 .xlsm 文件：公式、表格、格式设置、结构编辑和数据检查。读取公式单元格时，它会告知 AI 其中的值是刚刚计算得出的、从上次保存时保留的，还是从未计算过，从而避免过时数字出现在报告中。这是免费的社区版，采用 AGPL-3.0 许可。

产品页面 · llms.txt · 更新日志

**平台：**文件工具可在 Windows 和 Linux 上运行（此版本尚未在 macOS 上测试）。重新计算、数据透视表、PDF 导出和其他由 Excel 驱动的功能需要安装了 Microsoft Excel 的 Windows。

安装

此软件包需要 Python 3.12 或更高版本。请在 PowerShell 或终端中运行以下命令，而不是在 AI 聊天中运行。

**Claude Code 或 Codex CLI。**安装 uv，运行适用于你所用应用的命令，然后开始新会话：

claude mcp add xl -s user -- uvx kitchensink4xl

codex mcp add xl -- uvx kitchensink4xl

**Claude Desktop。**安装 uv 并重启 Claude Desktop。从最新版本下载 .mcpb 文件，然后打开 Settings > Extensions > Advanced settings > Install extension 并选择该文件。首次启动时会下载 Python 软件包，因此需要网络连接。

**其他任何本地 MCP 客户端。**将 uvx 用作命令，并将 kitchensink4xl 作为其参数；或者安装软件包，并将 kitchensink4xl 作为服务命令运行：

pip install kitchensink4xl

首次通过 uvx 启动时会构建环境，可能需要 20 到 30 秒；之后启动约需 2 秒。如果客户端在首次运行时超时，请先在终端中启动一次，然后重试。

功能

• 在使用公式值之前，告知该值是已计算、已缓存还是缺失，并列出受影响的单元格。
• 读取某个区域，或汇总大型表格，而不必将每一行都载入 AI 的上下文。
• 在现有工作簿中写入公式、值和数字格式。
• 插入和删除行列，同时让公式、表格、命名区域、图表和跨工作表引用自动跟随调整。
• 按照 Excel 的方式排序和筛选，并为客户或同事设置表格格式。
• 导入和导出 CSV 与 JSON。
• 在分享工作簿之前检查其结构问题。
• 在 Windows 上使用 Excel：实际重新计算、创建数据透视表、运行单变量求解、导出为 PDF，以及将工作表渲染为图像。

该服务总共提供 7 个工具、69 项操作；若按每项操作可执行的动作分别计数（例如每种工作表或表格更改），则共计 131 项。启动时，完整工具列表约占用 AI 工作记忆中的 5.5k 个 token。数据来自 scripts/measure_surface.py 和 scripts/count_operations.py。

标签为何重要

工作簿会存储每个公式上次计算出的答案，但不保证该答案是最新的。如果上游内容发生变化，却没有人重新计算，旧数字看起来仍像真的一样。KitchenSink4XL 会为它返回的每个公式结果标注状态：刚刚计算、沿用上次保存的结果，或尚未计算。手动输入的值没有标签，因为它们无需重新计算。需要时，xl_app 工具会调用一个私有的隐藏版 Excel 重新计算，并返回标记为已计算的结果。

保持工作簿完整的结构编辑

插入列会影响其右侧的所有内容：公式、总计、图表、表格，以及其他工作表中的命名区域。KitchenSink4XL 会移动应当移动的内容，并针对 Excel 自身处理公式、表格、命名区域、图表和跨工作表引用的行为进行测试。无法安全执行编辑时，它会拒绝操作并说明原因，而不是猜测。

七种工具与上下文开销

服务器会从第一条消息开始列出七种工具，无需启用任何工具。除 xl_help 外，每种工具都接受 op（要执行的操作）和 args（操作参数，其中包括工作簿的 path）。xl_help 会返回任何操作所需的参数和一个完整示例。Token 数量统计的是客户端收到的完整 tools/list 条目，数据来自 scripts/measure_surface.py。

你的 AI 会通过指定操作名称并传入参数来调用工具：

xl_read(op="get_grid_view", args={"path": "C:/data/budget.xlsx"})
xl_edit(op="set_cell", args={"path": "C:/data/budget.xlsx", "location": "C1", "value": "Total"})

如需了解工作流，请让你的 AI 调用 get_workflows。服务器自身的说明会在上述数字基础上增加约 500 个 Token。首次使用时才加载工具架构的客户端，在调用工具之前几乎不会产生开销。

希望使用范围更窄服务器的管理员可以设置 KS4XL_READ_ONLY=1，此时只会列出读取类操作；也可以在 KS4XL_FORBID 中列出要移除的工具或操作（参见 Configuration）。移除的内容不再计入开销。

安全模型

• 每次更改前，工作簿都会备份到同目录下隐藏的 .ks4xl-backups/ 文件夹中的两个轮换槽位。manage_backups 可列出、还原和清理这些备份。槽位仅记录通过此服务所做的更改；在 Excel 或其他程序中所做的编辑不会被记录。
• 保存操作是原子的，并会经过验证；每次写入后都会进行检查，如果检查失败，则会还原备份。保存期间，其他程序可能会有几毫秒无法找到工作簿路径，这与 Office 自身保存时一样；此服务自身的调用会等待保存完成。启用 verify_com=true（或为每次保存设置 KS4XL_VERIFY_COM=1）后，还必须确保保存的文件能在隐藏的 Excel 中正常打开。
• 普通单元格编辑会逐字节保留工作簿的其余内容（打印机设置、共享字符串、行高、图片、外部链接和其他部分），因此 Excel 打开结果时不会提示修复。结构性编辑使用的完整重写会一并保留这些内容，以及自定义属性、敏感度标签和修改密码。
• 保存前会扫描并列出写入器无法保留的工作簿部分；除非调用明确允许丢失相应类型的内容，否则会拒绝保存。
• 写入操作会遵守工作表和工作簿保护规则；如果保护设置禁止更改，则会以 PROTECTED 拒绝操作。
• 破坏性调用会保留工作簿原状的带标签快照，可按标签还原。
• 仅仅看起来像公式的文本绝不会被转换为公式。单元格类型决定其内容。
• 对有歧义的目标会拒绝操作，并列出所有候选项。
• xl_app 使用自己独立的隐藏 Excel 实例，不会使用你已打开的工作簿，也不会遗留多余的 Excel 进程。在 Excel 中打开的工作簿可以读取，但不能修改。
• 对于设置了修改密码的工作簿，任何会以编辑方式打开该工作簿的 xl_app 操作都会拒绝，并说明解决方法，以免 Excel 的密码对话框出现在你的桌面上。加密工作簿会在 Excel 启动前被拒绝，除非提供密码。
• query_range、export_range 和聚合操作会包含自动筛选器隐藏的行。Excel 的 SUBTOTAL 会跳过这些行，因此筛选工作表上的汇总结果可能与 Excel 状态栏中的不同。
• 请将 .ks4xl-backups/ 排除在云同步工具之外；每次编辑都会更改备份文件，同步客户端可能会锁定文件，拖慢保存速度。

隐私

此服务在你的计算机上运行。KitchenSink4AI 不会收到你的文件或使用数据。你的 AI 应用可能会根据该应用的设置和条款，将提示词、文件内容和工具结果发送给其自身的服务提供商。下文所述的更新检查每周最多联系一次 PyPI，且仅发送软件包名称和已安装版本。选择“立即更新”会从 PyPI 下载新版本；对于 Claude Desktop，则会从 GitHub 下载新软件包。此服务已关闭启动横幅，因此其运行所依托的框架不会自行检查版本。隐私政策涵盖产品、购买和支持事宜。

配置

启动设置是服务配置中的环境变量。它们只在启动时读取一次，任何工具调用、参数或提示词都无法更改这些设置。

我们会自动处理早期版本中的设置：旧版默认设置（KS4XL_MODE 设为 lite、full 或 everything，或 KS4XL_PACK_POLICY=auto）会被忽略，并显示一行通知；锁定工具的设置（KS4XL_PACK_POLICY=locked 或 KS4XL_MODE 中列出工具组）会停止启动，并显示说明应改用何种设置的消息。若要自行限制工具，请使用 KS4XL_READ_ONLY 或 KS4XL_FORBID。

沙盒。 设置 KS4XL_ALLOWED_ROOTS 后，路径包含检查会针对规范路径运行，因此 ..\ 路径遍历、符号链接和联接点、短文件名、大小写技巧以及仿冒文件夹名称都会被拦截。被拦截的调用会返回带类型的错误，指出相关路径和允许的根目录，且不会打开任何文件。

更新检查和更新通知。 每周最多一次，在你使用工具后，服务会在后台向 PyPI 查询 kitchensink4xl 的最新版本。请求仅包含软件包名称和已安装的版本，不包含任何文档、文件名或标识符。如果有更新版本，且服务通过 uvx 或 Claude Desktop 扩展运行，你的 AI 应用会显示一条简短通知，其中包含「立即更新」和「暂不更新」选项（如果应用支持）。否则，你的 AI 会提及一次新版本并提供更新选项。除非你在通知中选择「立即更新」，或要求 AI 更新，否则服务绝不会下载或安装新版本。若要关闭通知，请要求 AI 关闭 KitchenSink4XL 更新通知；KS4XL_UPDATE_NOTICES=off 会在所有位置关闭通知，而 KS4XL_UPDATE_CHECK=off 会完全关闭检查（KS4XL_NO_UPDATE_CHECK=1 也有效）。此设置保存在服务自己的状态文件夹中，因此更新后仍会保留。

Claude Desktop 扩展设置。 每次保存时都使用 Excel 验证会启用隐藏的 Excel 打开检查（默认关闭，因为每次写入时都会因此多经过一次 Excel）。将服务限制在一个文件夹内会将服务访问的所有路径（包括读取路径）限制在你选择的文件夹内。

{"mcpServers": {"xl": {"command": "kitchensink4xl"}}}

已知限制

• com_render_sheet 需要已登录的桌面会话。 将工作表渲染为图像时会使用 Excel 剪贴板，而非交互式会话中的隐藏 Excel 无法使用剪贴板。其他所有 xl_app 操作都可在无人值守的情况下运行。
• 这是桌面工具，而非共享服务。 服务在你的计算机上以你的账户运行，xl_app 会驱动 Windows 会话中的 Excel。它并非设计为供团队通过单个安装实例共享使用。
• 删除工作表会破坏对它的引用。 指向已删除工作表的公式和名称会显示 #REF!，与 Excel 中的表现相同。重命名工作表则会改写这些引用。如果不确定，请先审计引用。
• 文件编辑无法重新计算。 通过文件工具写入后，下游单元格会保留旧的缓存值，直到 Excel 重新计算。标签会指出受影响的值；在 xl_app 中调用 recalculate 即可修复。

从 1.x 升级

2.0 版将 1.2.x 中的 69 个独立工具重新归类为上述七个工具。除了已移除的 enable_tools 和 disable_tools 之外，每个操作都保留原名称；但现在需要将其作为某个工具的操作来调用：例如，使用 xl_edit 并设置 op="set_cell"，而不是调用名为 set_cell 的工具。命令名称、软件包名称和安装方式均未改变。

少数值的拼写有所变化，但旧拼写仍然可用：条件格式和数据验证的值现在使用 snake_case（greater_than、last_7_days、text_length），而 manage_chart 使用 at_cell，不再使用 anchor。你之前的 KS4XL_MODE 和 KS4XL_PACK_POLICY 默认值无需修改；请参阅上文的设置说明。docs/surface_map.md 列出了每个 1.2.5 工具对应的替代工具，以及所有变更的值；get_workflows 中的 migrate-from-v1 配方会向你的 AI 提供相同的映射。变更日志列出了其他所有变更。

测试

测试套件在 tests/unit 中包含 5,340 项测试，并会在每个拉取请求上运行。结构性编辑会根据 Excel 自身的重新计算结果进行检查；涵盖所有已记录函数类别的公式都会写入并重新打开，且不会出现修复提示；测试工作簿还包含只有 Excel 才能创建的功能，例如数据透视表、切片器和形状。另有一组独立的门禁测试会驱动真实的 Excel，并在 Windows 上本地运行。

报告问题

如果出现故障、意外拒绝操作或返回错误数值，请提交问题。请使用占位数据重建结构，而不要附上私人工作簿，并附上 get_server_info 的输出；该输出专为安全分享而设计。欢迎在此处提出功能建议。安全问题请按照 SECURITY.md 中的说明处理。

Business 版

Business 版将这些工具与 Windows 安装程序、签名更新渠道以及 Business 条款下的支持服务相结合。检查更新时会告知你是否有适用的版本可用，且不会自动安装任何内容。请参阅定价。Community 版在 AGPL 许可下始终免费，包括符合其条款的商业用途。

贡献

欢迎提交错误报告、修复、测试和文档。请参阅 CONTRIBUTING.md；首次贡献者需同意贡献者许可协议。

许可证

KitchenSink4XL 采用双重许可。

• AGPL-3.0。 任何人均可免费使用，包括企业，但必须遵守 AGPL。其条款要求你在分发软件或通过网络提供软件时，分享源代码及所做的修改。
• 商业许可证。 适用于希望将 KitchenSink4XL 集成到自有产品或服务中，且无需承担 AGPL 源代码共享义务的组织。请联系 [email protected]。

本软件按原样提供，不附带任何形式的保证，并受许可证条款约束。

版权所有 (c) 2026 Alvut Consulting, LLC。KitchenSink4AI 是 Alvut Consulting, LLC 的产品线。KitchenSink4AI 工具在 AI 编码助手的帮助下构建，每个版本发布前都会通过完整的测试套件。

与 Microsoft Corporation 无关联，也未获其认可或赞助。Microsoft 和 Excel 是 Microsoft 集团公司的商标。GitHub 和 Copilot 是 Microsoft 集团公司的商标。Claude 是 Anthropic 的商标。Codex 和 OpenAI 是 OpenAI 的商标。所有其他商标均为其各自所有者的财产。