xlide-mcp

An MCP server for the inside of an Office file. Read, write, analyze and test the VBA in Excel, Word, PowerPoint and Access, and edit the document around it. Visual Basic 6 projects open the same way.

VBA, Power Query and OOXML worksheet edits need no Office installation and run on Windows, macOS and Linux. Reading .xlsb and .xls cells, writing .xlsb cells, and running macros or tests need Windows with the desktop application.

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

Why

An agent asked to fix a macro works from a copied snippet with no idea what else is in the project, or asks the user to export the modules and paste them back afterwards. Both treat the Office file as opaque. The VBA project, the form designs and the M code are all readable and writable without opening the application at all.

This server makes that reachable, and bounds it. A write is refused if the module changed since it was read. An analysis error fails the change. A run happens in an application the server created and holds a deadline over. Anything that cannot be undone is the user's decision.

Implementations

Other languages go in sibling directories. Python is normative: it tracks the upstream libraries, and ports track it. See docs/porting.md.

Install and run

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

Point a client at it. For Claude Desktop, Claude Code or any client that launches a server over stdio:

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

For VS Code, put this in .vscode/mcp.json at the workspace root. VS Code uses servers here; the portable .mcp.json format above uses mcpServers.

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

Run MCP: List Servers in VS Code to start xlide and inspect its output if it does not register. The server prints its version and allowed roots to stderr on startup. The VS Code configuration format and commands are described in VS Code's MCP guide.

Or install nothing and let uv fetch it on first run. uv is one binary and installs its own Python, so a machine with neither can still run this:

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

The live extra is safe to ask for on every platform: what it pulls in is marked sys_platform == 'win32', so off Windows it resolves to nothing and the same configuration works everywhere. Drop the --from pair for the file layer alone. uvx takes the newest published version unless you pin it, as xlide-mcp@1.2.0.

There is a Dockerfile for the file layer, which is the part that needs no Office installation. Mount the folder holding the files at /workspace, because that is the root the container is bounded to:

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

--root is the security boundary. Every path a tool accepts is resolved, symlinks included, and refused unless it lands inside a root. Add --read-only to allow reads and analysis and refuse every write.

Call xlide_doctor first from a new client: it reports the workspace roots, which layers are installed, which Office applications this machine has, and whether each one has the Trust Center setting that module injection needs.

What it does

Files - the VBA project and the document it lives in. Most file tools need no Office installation; binary Excel grids use Excel on Windows.

The code project

xlide_edit_module accepts preview_only=true to check a batch of line edits and return its proposed diff without saving. The preview's content token can be used to apply the same edits if the module has not changed. xlide_search_modules returns tokens for matched modules, so its line numbers can also be passed directly to a guarded edit. Broad searches can be paged with offset and next_offset; total_match_count reports how many matching lines exist across all pages. xlide_list_procedures returns a content token for guarded edits at the listed lines. Reading an empty module returns its empty body and token. Writing an identical module or applying an unchanged module import skips the save; the response reports saved=false. Applying an unchanged export leaves the existing .bas and .cls files untouched. Long Power Query formulas can be read by line; the read returns a token that xlide_write_query can use to refuse a stale change. Large form designs can be read in pages with offset and next_offset. Office file, VBA module and Power Query lists also return next_offset when a later page is available. For crowded drawing layers, pass sheet to xlide_list_shapes and follow its next_offset to read later shapes. Worksheet lists mark unreadable visibility or pivot metadata as unknown, and formatted or rich text cell reads name the cell when decoding fails instead of returning a blank. An Excel-backed worksheet survey refuses malformed output instead of dropping sheets. An Excel-backed cell read refuses a partial grid instead of labeling it as the full range. Form summary lists use the same offset and next_offset paging. Form reads distinguish missing properties or sections from a read failure, and an unreadable Access report collection fails instead of appearing empty. Procedure lists also return next_offset for long modules. Structural validation problems can be read with offset and next_offset. Access catalog lists return a next_offsets entry for each included collection. Long saved query SQL is previewed in the catalog; xlide_read_access_query returns the full text in character pages with a content token. The list actions for tables, names, validation, conditional formats, hyperlinks and comments also accept offset and max_results and return next_offset. Merging cells keeps only the top-left value. xlide_format_cells refuses to clear other values or formulas unless allow_overwrite=true is passed. xlide_sort_rows sorts a range, table or filter with ordered keys; xlide_remove_duplicates keeps the first matching row. xlide_copy_cells copies between sheets with Paste Special options and requires allow_overwrite=true. xlide_update_shape changes a shape's position, name, text, alt text or visibility without removing it; it also changes a Forms control's linked cell or list range.

xlide_check_cells lists Excel's green-triangle error checks, including numbers stored as text and inconsistent formulas, with paging for long lists.

The document around it

Execution - Windows with the desktop application.

xlide_run_macro, xlide_run_vba, xlide_run_tests, xlide_compile_check