Read, write, analyze, test and diff the VBA in Office files, and the document around it
The MCP server provides capabilities to read, write, analyze, test, and diff VBA contained in Office files, along with the document context around that VBA. Its focus is on working with VBA within Office documents, including comparing changes via diff workflows.
🛠️ Key Features
Read VBA in Office files
Write VBA in Office files
Analyze VBA and surrounding document content
Test VBA
Diff VBA and related document content
🚀 Use Cases
Inspect existing VBA code in Office documents
Modify VBA within Office files
Validate VBA behavior through testing
Compare document/VBA versions using diff
⚡ Developer Benefits
Enables programmatic workflows for VBA editing and verification
Supports change tracking by diffing VBA and surrounding document content
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.
code
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.
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:
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.4.
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:
--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.
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.
Your Office applications - Windows with the desktop application. The one
place this server acts inside an application the user is running, and only on
the file named.
xlide_live_read_module accepts line ranges for long unsaved source and returns
a content token for comparing that source with the saved module.
Both analysis tools return next_offset when findings exceed a page, while
keeping their full severity counts.
Formats
Host
Extensions
Excel
.xlsm.xlsb.xlam.xls, and .xlsx for everything except VBA
Word
.docm.dotm.doc
PowerPoint
.pptm.potm
Access
.accdb.mdb
Visual Basic 6
.vbp
VBA reads and writes in all of them. Power Query is available in .xlsx, .xlsm,
.xlsb and .xlam; package-based worksheet edits are available in .xlsx,
.xlsm and .xlam. A .xlsx has no VBA project by design and is listed anyway,
since its queries and sheets are fully reachable.
A recognized extension outside those sets is listed with the reason it cannot be
opened. Nothing drops out of a listing without saying why.
Excel, Word and PowerPoint write no VBA project into a macro-enabled file until
its first macro exists, so a .xlsm nobody has written code in yet has none.
That is an ordinary file: the listings answer empty, and the first module
written gives it the project its application would have made.
An Access database that has never held code can likewise have no project;
xlide_write_module creates it with the first module, or
xlide_create_project adds an empty one to an existing .accdb.
A .xlsb keeps its grid in binary records and a .xls inside a compound file,
neither of them OOXML. On Windows with Excel, those go through Excel, and the
result says source: excel and recalculated: true, because opening the
workbook is what produced the values.
This path returns values only; .xls cells cannot be written through this server.
Seeing what changed
An Office file is one binary blob to git, so a commit that changed a line of VBA
and one that replaced the whole project are the same three words: Binary files differ. Two ways out, both reading the file through the same renderer.
xlide_git_changes reports what changed since any revision, one entry per module
and query, each with a unified diff. Call it before committing, or to review what
an agent just did.
xlide-mcp --textconv is a git textconv driver. Wire it up once and the file
diffs as text everywhere git looks:
Public Sub Greet()
- MsgBox "hello"+ MsgBox "hello, world"+ Debug.Print Now
End Sub
That is git diff on a .xlsm. git show and git log -p convert too.
Inside VS Code beside XLIDE,
there is a third way. Every write tells a running XLIDE what changed, and a
module write carries its before and after, so XLIDE marks the module as an agent
edit in its project tree, opens the diff, and offers Keep and Revert, as it does
for its own agent tools. It needs an XLIDE that listens for this;
docs/xlide-vscode-bridge.md is the protocol. With
no XLIDE running, nothing changes.
binary diff=vba rather than diff=vba alone. The binary macro means
-diff -merge -text, and the later diff=vba overrides only its -diff, so the
file keeps -text and git never applies end-of-line conversion to a container it
would corrupt.
In VS Code, any side of a diff that comes out of git history renders through the
driver, because the git extension reads blobs with git show --textconv.
Comparing two revisions of a workbook therefore shows VBA. The Source Control
panel's working-tree diff does not: the right-hand side there is the file on
disk, still binary.
Both routes render VBA, Power Query and the sheet inventory. Cell values are not
included, and the first line of every rendered file says so, because a reader
who does not know the scope takes an empty diff for an unchanged workbook. git
still stores the blob either way, so merges stay binary.
The rules it works by
These are in the server's own instructions, so every agent that connects reads
them whether or not the user configured anything.
The VBA inside the file is the only source of truth for it. Exported .bas and
.cls files are copies and go stale.
A read returns a content token. Pass it back on the write, and the write is
refused if anything changed the module in between.
Analysis after every change, and an error is a build failure.
A run happens in an Office instance the server created and can therefore
terminate. The user's own applications are touched only through the three
tools above, on the file named: unsaved work is closed only when the call says
to save or discard it, and a process is ended only when asked, and only the
one Windows names as holding the file.
Anything hard to undo is the user's decision: deleting a module, overwriting
cells that hold data, writing to a project that is signed or password-protected.
Cell overwrites and writes to signed or protected projects are refused until
the call carries the flag that allows them.
A cell value is what Excel last calculated. A formula written here has no result
in the file until Excel next opens it. calculate=true works results out with
pyOfficeEditor's formula engine, which names any cell it could not.
CodeQL and Semgrep scan the server and release workflows, pip-audit checks the
runtime dependencies, and ClamAV and YARA-X, with the YARA Forge rules, scan
every tracked file and the built wheel and sdist, on every push, pull request,
daily run and release. An unexpected finding, scan warning or missing
scan stops a release. Each successful release carries its security report and
the SARIF results as downloadable assets. Dependabot proposes dependency and
workflow updates for review.
The live editor session the xlide_live_* tools talk to.
Contributing
bash
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
The generated contract under contract/ must stay current; the test
suite fails if it does not. After changing a tool: