XLIDE

xlide-mcp

用于深入操作 Office 文件的 MCP 服务。 读取、写入、分析和测试 Excel、Word、PowerPoint 和 Access 中的 VBA，并编辑周边文档。Visual Basic 6 项目也能以相同方式打开。

编辑 VBA、Power Query 和 OOXML 工作表无需安装 Office，可在 Windows、macOS 和 Linux 上运行。读取 .xlsb 和 .xls 单元格、写入 .xlsb 单元格以及运行宏或测试，则需要在 Windows 上使用桌面应用。

xlide_list_projects                -> Budget.xlsm
xlide_project_info   Budget.xlsm   -> 4 modules, 2 sheets, 1 query, not signed
xlide_read_module    Helpers       -> the source, and a content token
xlide_write_module   Helpers       -> guarded by that token
xlide_analyze        Budget.xlsm   -> 0 errors, 2 warnings
xlide_run_tests      Budget.xlsm   -> 12 passed

原因

当 Agent 被要求修复宏时，它只能依据复制出来的代码片段工作，不了解项目中的其他内容；或者会要求用户导出模块并在之后粘贴回去。这两种做法都把 Office 文件当成了不透明的整体。VBA 项目、表单设计和 M 代码都可以在完全不打开应用程序的情况下读取和写入。

本服务让这些操作触手可及，同时也设定了边界。如果模块自读取后发生了变化，写入就会被拒绝。分析出错会导致更改失败。运行操作会在服务创建并受截止时间限制的应用程序中进行。任何无法撤销的操作都由用户决定。

实现

目录	语言	状态
python/	Python 3.10+	参考实现

其他语言的实现放在同级目录中。Python 实现具有规范性：它跟踪上游库，其他语言的移植版本则跟踪它。请参阅 docs/porting.md。

安装并运行

pip install xlide-mcp              # reads and writes files, any platform
pip install "xlide-mcp[live]"      # adds running macros and tests, Windows
xlide-mcp --root /path/to/your/files

将客户端指向它。对于 Claude Desktop、Claude Code 或任何通过 stdio 启动服务的客户端：

{
  "mcpServers": {
    "xlide": {
      "command": "xlide-mcp",
      "args": ["--root", "/path/to/your/files"]
    }
  }
}

对于 VS Code，将以下内容放入工作区根目录下的 .vscode/mcp.json。VS Code 在这里使用 servers；上面的通用 .mcp.json 格式使用 mcpServers。

{
  "servers": {
    "xlide": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "xlide-mcp[live]", "xlide-mcp", "--root", "${workspaceFolder}"]
    }
  }
}

在 VS Code 中运行 MCP: List Servers 以启动 xlide；如果未注册，请检查其输出。服务启动时会将版本和允许的根目录打印到 stderr。VS Code 配置格式和命令详见 VS Code 的 MCP 指南。

也可以不安装任何内容，让 uv 在首次运行时获取它。uv 是一个二进制文件，并会安装自己的 Python，因此即使机器上两者都没有，也仍可运行：

{
  "mcpServers": {
    "xlide": {
      "command": "uvx",
      "args": [
        "--from", "xlide-mcp[live]",
        "xlide-mcp", "--root", "/path/to/your/files"
      ]
    }
  }
}

live extra 在所有平台上都可以安全启用：它引入的依赖标记为 sys_platform == 'win32'，因此在 Windows 之外不会解析出任何内容，同一配置可在任何地方使用。若只需要文件层，请删去 --from 参数对。uvx 默认使用最新发布版本，除非指定版本，例如 [email protected]。

文件层提供了一个 Dockerfile，它无需安装 Office。将存放文件的文件夹挂载到 /workspace，因为这是容器的边界根目录：

docker build -t xlide-mcp .
docker run --rm -i -v "$PWD:/workspace" xlide-mcp

--root 是安全边界。工具接受的每个路径都会经过解析（包括符号链接），只有位于某个根目录内时才会被允许。

添加 --read-only 可允许读取和分析，并拒绝所有写入操作。

在新客户端中，先调用 xlide_doctor：它会报告工作区根目录、已安装的层、这台机器上的 Office 应用，以及每个应用是否具有模块注入所需的信任中心设置。

功能

文件——VBA 项目及其所在的文档。大多数文件工具无需安装 Office；二进制 Excel 网格需要在 Windows 上使用 Excel。

代码项目

发现	xlide_list_projects、xlide_project_info、xlide_validate_project、xlide_create_project、xlide_doctor
模块	xlide_list_modules、xlide_read_module、xlide_write_module、xlide_edit_module、xlide_rename_module、xlide_delete_module、xlide_list_procedures、xlide_search_modules
分析	xlide_analyze、xlide_analyze_source、xlide_rules
窗体	xlide_list_forms、xlide_read_form、xlide_manage_form、xlide_edit_form
引用和目录	xlide_list_references、xlide_manage_reference、xlide_access_catalog、xlide_read_access_query
源代码管理	xlide_export_modules、xlide_import_modules、xlide_git_changes
xlide_edit_module 接受 preview_only=true，用于检查一批行编辑并返回拟议的差异，而不保存。只要模块没有更改，预览的内容令牌就可用于应用相同的编辑。
xlide_search_modules 会为匹配的模块返回令牌，因此其行号也可以直接传递给受保护的编辑。
可使用 offset 和 next_offset 对宽泛的搜索结果分页；total_match_count 会报告所有页面中匹配行的数量。
xlide_list_procedures 会为所列行的受保护编辑返回内容令牌。读取空模块时，会返回空正文和令牌。
写入内容相同的模块或应用未更改的模块导入时会跳过保存；响应会报告 saved=false。
应用未更改的导出时，现有 .bas 和 .cls 文件会保持不变。
可按行读取较长的 Power Query 公式；读取结果会返回令牌，xlide_write_query 可用它拒绝过时的更改。
大型窗体设计可以使用 offset 和 next_offset 分页读取。
Office 文件、VBA 模块和 Power Query 列表也会在有后续页面时返回 next_offset。
对于元素密集的绘图层，可将 sheet 传递给 xlide_list_shapes，并根据其 next_offset 读取后续形状。
工作表列表会将无法读取的可见性或数据透视表元数据标记为未知；读取格式化或富文本单元格时，如果解码失败，会指出单元格，而不是返回空白。
基于 Excel 的工作表调查在输出格式错误时会拒绝返回结果，而不是丢弃工作表。
基于 Excel 的单元格读取在网格不完整时会拒绝返回结果，而不是将其标记为完整范围。
窗体摘要列表使用相同的 offset 和 next_offset 分页方式。
读取窗体时会区分缺少属性或区域与读取失败；无法读取 Access 报表集合时会报错，而不会将其显示为空。
较长模块的过程列表也会返回 next_offset。
可使用 offset 和 next_offset 分页读取结构验证问题。
Access 目录列表会为每个包含的集合返回一个 next_offsets 条目。
目录中会预览较长的已保存查询 SQL；xlide_read_access_query 会通过内容令牌按字符分页返回完整文本。
表格、名称、验证、条件格式、超链接和批注的 list 操作也接受 offset 和 max_results，并返回 next_offset。
合并单元格时只保留左上角的值。除非传入 allow_overwrite=true，否则 xlide_format_cells 不会清除其他值或公式。
xlide_sort_rows 使用有序键对范围、表格或筛选结果排序；xlide_remove_duplicates 会保留第一个匹配行。xlide_copy_cells 使用“选择性粘贴”选项在工作表之间复制，并要求传入 allow_overwrite=true。
xlide_update_shape 可更改形状的位置、名称、文本、替代文本或可见性，而不会将其删除；它还可更改窗体控件的关联单元格或列表范围。

xlide_check_cells 会列出 Excel 的绿色三角形错误检查结果，包括以文本形式存储的数字和不一致的公式；长列表支持分页。

周边文档

Power Query	xlide_list_queries、xlide_read_query、xlide_write_query（设置、重命名、移除、加载、卸载）
工作表和单元格	xlide_list_sheets、xlide_read_cells、xlide_write_cells、xlide_evaluate_formula、xlide_check_cells、xlide_format_cells、xlide_sort_rows、xlide_remove_duplicates、xlide_copy_cells
结构	xlide_manage_sheet、xlide_manage_rows_columns
表格和名称	xlide_manage_table、xlide_manage_name、xlide_manage_filter
规则、链接和批注	xlide_manage_validation、xlide_manage_conditional_format、xlide_manage_hyperlink、xlide_manage_comment、xlide_page_setup
形状和图表	xlide_list_shapes、xlide_manage_shape、xlide_update_shape、xlide_set_shape_macro、xlide_add_chart

执行 - 在 Windows 上使用桌面应用程序。

xlide_run_macro、xlide_run_vba、xlide_run_tests、xlide_compile_check 你的 Office 应用程序——带桌面应用程序的 Windows。这是此服务在用户正在运行的应用程序内执行操作的唯一场景，而且只针对指定的文件。

xlide_is_open、xlide_open_in_app、xlide_close_in_app

实时编辑器——Visual Basic Editor 中正在运行的 xlide_vbide 会话。

xlide_live_sessions、xlide_live_state、xlide_live_request、xlide_live_read_module

xlide_live_read_module 支持读取未保存的长源代码的指定行范围，并返回内容令牌，以便将该源代码与已保存的模块进行比较。 如果分析工具返回的发现结果超出一页，会返回 next_offset，同时保留完整的严重性计数。

格式

主机	扩展名
Excel	.xlsm .xlsb .xlam .xls，以及仅限非 VBA 内容的 .xlsx
Word	.docm .dotm .doc
PowerPoint	.pptm .potm
Access	.accdb .mdb
Visual Basic 6	.vbp

这些格式均支持 VBA 读取和写入。.xlsx、.xlsm、.xlsb 和 .xlam 支持 Power Query；.xlsx、.xlsm 和 .xlam 支持基于包的工作表编辑。.xlsx 按设计不包含 VBA 项目，但仍列在其中，因为它的查询和工作表都可以完整访问。

对于这些集合之外的已识别扩展名，列表会说明无法打开的原因。列表中的每个文件都会说明情况，不会无故消失。

Excel、Word 和 PowerPoint 不会在启用宏的文件中写入 VBA 项目，直到其中首次创建宏。因此，一个尚未写入代码的 .xlsm 不会包含项目。这是正常文件：列表会返回空结果，而写入第一个模块后，就会为它创建应用程序本应创建的项目。 从未包含过代码的 Access 数据库同样可能没有项目；xlide_write_module 会在写入第一个模块时创建项目，或者 xlide_create_project 会在现有 .accdb 中添加一个空项目。

.xlsb 将网格保存在二进制记录中，.xls 则位于复合文件内；两者都不是 OOXML。在安装 Excel 的 Windows 上，这两种格式都会通过 Excel 处理，结果会显示 source: excel 和 recalculated: true，因为这些值是在打开工作簿时生成的。 此路径仅返回值；无法通过此服务写入 .xls 单元格。

查看变更

对于 git 来说，Office 文件就是一个二进制块，因此，修改了一行 VBA 的提交和替换了整个项目的提交，都会显示为同样的三个词：Binary files differ。有两种解决办法，两者都通过同一个渲染器读取文件。

xlide_git_changes 会报告自任意版本以来的变更，每个模块和查询各列一项，并附带统一差异。可在提交前调用，也可用来审查 Agent 刚完成的操作。

xlide-mcp --textconv 是一个 git textconv 驱动程序。配置一次后，git 查看文件差异时就会将其显示为文本：

echo '*.xlsm binary diff=vba' >> .gitattributes
git config diff.vba.textconv "xlide-mcp --textconv"
git config diff.vba.cachetextconv true

 Public Sub Greet()
-    MsgBox "hello"
+    MsgBox "hello, world"
+    Debug.Print Now
 End Sub

这就是对 .xlsm 执行 git diff。git show 和 git log -p 也会进行转换。

在 VS Code 中与 XLIDE 配合使用时，还有第三种方式。每次写入都会告知正在运行的 XLIDE 发生了什么变化，而模块写入会同时携带修改前和修改后的内容，因此 XLIDE 会在项目树中将该模块标记为 Agent 编辑，打开差异，并提供保留和还原选项，就像处理自己的 Agent 工具所做的修改一样。这需要 XLIDE 监听此类通知；docs/xlide-vscode-bridge.md 介绍了相关协议。如果没有运行 XLIDE，则不会有任何变化。

使用 binary diff=vba，而不是单独使用 diff=vba。binary 宏表示 -diff -merge -text，后面的 diff=vba 只会覆盖其中的 -diff，因此文件仍保留 -text，git 也不会对容器应用行尾转换，以免损坏容器。

在 VS Code 中，差异的任一侧如果来自 git 历史记录，都会通过驱动程序渲染，因为 git 扩展会使用 git show --textconv 读取对象。因此，比较工作簿的两个版本时会显示 VBA。源代码管理面板中的工作树差异则不会：那里的右侧是磁盘上的文件，仍是二进制文件。

这两种方式都会渲染 VBA、Power Query 和工作表清单。不包含单元格值，并且每个渲染文件的第一行都会说明这一点，因为不了解范围的读者可能会把空差异误认为工作簿没有变化。无论采用哪种方式，git 仍会存储二进制块，因此合并仍以二进制方式进行。

运作规则

这些规则写在服务自身的说明中，因此每个连接的 Agent 都会读取，无论用户是否进行过配置。

• 文件中的 VBA 是唯一可信来源。导出的 .bas 和 .cls 文件只是副本，可能会过时。
• 读取操作会返回内容令牌。写入时传回该令牌；如果期间模块发生了变化，写入就会被拒绝。
• 每次变更后都会进行分析，出现错误即视为构建失败。
• 运行操作发生在服务创建的 Office 实例中，因此可以终止该实例。只有通过上述三个工具，才会操作用户自己的应用程序，并且仅针对指定文件：只有当调用要求保存或放弃时，才会关闭未保存的工作；只有在收到结束进程的请求时才会结束进程，且只结束 Windows 标识为持有该文件的进程。
• 难以撤销的操作由用户决定：删除模块、覆盖包含数据的单元格、写入已签名或受密码保护的项目。在调用中携带允许这些操作的标记之前，覆盖单元格以及写入已签名或受保护的项目都会被拒绝。
• 单元格值是 Excel 上次计算出的结果。在此处写入的公式，在 Excel 下次打开文件之前不会在文件中产生结果。calculate=true 会通过 pyOfficeEditor's 公式引擎计算结果，并指出无法计算的单元格。

安全

请通过私密漏洞报告报告漏洞，而不要提交公开议题。SECURITY.md 说明了需要提供哪些信息，以及哪些版本会获得修复。

CodeQL 和 Semgrep 会扫描服务和发布工作流，pip-audit 会检查运行时依赖项，而 ClamAV 和 YARA-X（使用 YARA Forge 规则）会扫描每个受版本控制的文件，以及构建的 wheel 和 sdist；这些扫描会在每次推送、拉取请求、每日运行和发布时执行。发现意外问题、扫描警告或缺少扫描都会阻止发布。每次成功发布都会附带安全报告和 SARIF 结果，供下载。Dependabot 会提出依赖项和工作流更新，供审核。

基于

pyOpenVBA	以纯 Python 读写 Office 文件中的 VBA、UserForms 和 Power Query。
pyOfficeEditor	文档操作层：单元格、公式、格式、表格、验证、行和列。
pyVBAanalysis	静态分析器：165 项诊断，针对每种宿主的对象模型进行评估。
pyVBAharness	在桌面版 Office 中运行 VBA，并由强制执行时限的监督器进行监控。
XLIDE for VS Code	工具层、内容令牌保护机制和 Agent 指令的来源。
xlide for the VBE	xlide_live_* 工具所连接的实时编辑器会话。

贡献

cd python
pip install -e ".[dev,live]"
python -m pytest              # the file layer, no Office needed
python -m pytest -m live      # the rest, real Office, Windows only
python -m ruff check src tests tools

contract/ 下生成的契约必须保持最新；否则测试套件会失败。修改工具后：

python tools/export_contract.py
python tools/export_conformance.py

许可证

MIT。