xlide_mcp

# xlide-mcp

[![PyPI version](https://img.shields.io/pypi/v/xlide-mcp)](https://pypi.org/project/xlide-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/xlide-mcp)](https://pypi.org/project/xlide-mcp/)
[![Downloads](https://static.pepy.tech/badge/xlide-mcp/month)](https://pepy.tech/projects/xlide-mcp)
[![CI](https://github.com/WilliamSmithEdward/xlide_mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/WilliamSmithEdward/xlide_mcp/actions/workflows/ci.yml)
[![Security](https://github.com/WilliamSmithEdward/xlide_mcp/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/WilliamSmithEdward/xlide_mcp/actions/workflows/security.yml)
[![Malware scan](https://github.com/WilliamSmithEdward/xlide_mcp/actions/workflows/malware-scan.yml/badge.svg?branch=main)](https://github.com/WilliamSmithEdward/xlide_mcp/actions/workflows/malware-scan.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/WilliamSmithEdward/xlide_mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/WilliamSmithEdward/xlide_mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/WilliamSmithEdward/xlide_mcp/blob/main/LICENSE)

[![xlide-excel-word-powerpoint-access-office-vba-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/WilliamSmithEdward/xlide_mcp/badges/card.svg)](https://glama.ai/mcp/servers/WilliamSmithEdward/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

| Directory | Language | Status |
|---|---|---|
| [`python/`](python/) | Python 3.10+ | Reference implementation |

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

## Install and run

```bash
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:

```json
{
  "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`.

```json
{
  "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](https://code.visualstudio.com/docs/agent-customization/mcp-servers).

Or install nothing and let [uv](https://github.com/astral-sh/uv) fetch it on
first run. uv is one binary and installs its own Python, so a machine with
neither can still run this:

```json
{
  "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.3`.

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:

```bash
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*

| | |
|---|---|
| Discover | `xlide_list_projects`, `xlide_project_info`, `xlide_validate_project`, `xlide_create_project`, `xlide_doctor` |
| Modules | `xlide_list_modules`, `xlide_read_module`, `xlide_write_module`, `xlide_edit_module`, `xlide_rename_module`, `xlide_delete_module`, `xlide_list_procedures`, `xlide_search_modules` |
| Analysis | `xlide_analyze`, `xlide_analyze_source`, `xlide_rules` |
| Forms | `xlide_list_forms`, `xlide_read_form`, `xlide_manage_form`, `xlide_edit_form` |
| References and catalog | `xlide_list_references`, `xlide_manage_reference`, `xlide_access_catalog`, `xlide_read_access_query` |
| Source control | `xlide_export_modules`, `xlide_import_modules`, `xlide_git_changes` |

`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*

| | |
|---|---|
| Power Query | `xlide_list_queries`, `xlide_read_query`, `xlide_write_query` (set, rename, remove, load, unload) |
| Sheets and cells | `xlide_list_sheets`, `xlide_read_cells`, `xlide_write_cells`, `xlide_evaluate_formula`, `xlide_check_cells`, `xlide_format_cells`, `xlide