ExStruct CLI
A Python package, CLI and MCP server: Excel workbooks become structured JSON for LLMs and edits go through patches with a dry run
- 203 ★ on the repository
- Last commit
- BSD-3-Clause
Extended access
Why this level
- `exstruct patch` and `make` write changes to Excel workbooks, and with `--backend auto` on Windows the real edit may switch to Excel COM
- The MCP server reads and writes files in the `--root` working folder, and the JSON export keeps formulas and the whole workbook content
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/exstructDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- `exstruct patch` and `make` write changes to Excel workbooks, and with `--backend auto` on Windows the real edit may switch to Excel COM
- The MCP server reads and writes files in the `--root` working folder, and the JSON export keeps formulas and the whole workbook content
This is third-party code. Review the repository files before installing.
What it does
ExStruct reads Excel workbooks into structured data and applies patch-based edits through a shared core. The command `exstruct input.xlsx > output.json` exports per sheet the cells, shapes, charts, SmartArt, table candidates, merged cells, print areas and formulas (`formulas_map`). Output formats are JSON (compact by default, `--pretty` for reading), YAML and TOON. Extraction modes depend on the environment. `light` parses OOXML directly and needs neither Excel nor LibreOffice, `libreoffice` on systems without COM adds shapes, connectors and charts, `standard` and `verbose` use Excel COM on Windows and give the most detail, and `verbose` also emits hyperlinks. Editing follows a validate, preview, apply order: `exstruct validate`, then `exstruct patch --dry-run` with a look at `PatchResult`, and only then the real run. `exstruct make` creates a new workbook, and `exstruct ops list` and `ops describe` show the operation schema. The same operations are exposed by the `exstruct-mcp` MCP server with nine tools for reading ranges and formulas, extraction, sheet images, and creating and patching workbooks. The repository also holds the `exstruct-cli` skill that walks an agent through the safe editing order.
Who it is for. Analysts and engineers who prepare Excel documents for RAG and LLMs or let an agent edit working books and want to see the edit beforehand.
Good fit when
- Excel tables have to be prepared for RAG: `exstruct input.xlsx --mode light` returns cells, table candidates and print areas without Excel installed
- A form with merged cells and shapes loses structure in an ordinary import: ExStruct keeps merges, arrows and charts, as the README form example shows
- An agent edits a workbook and the result must be seen in advance: `exstruct patch --dry-run` shows a `PatchResult` with warnings and diffs
- Tokens cost money: compact JSON by default and disabled backend metadata shrink the output
- Sheets are needed as PDF and PNG: `--pdf --image` makes them when Excel COM is available
Not a fit when
- You need an ordinary workbook edit from Python code: the README itself recommends `openpyxl` or `xlwings` for that
- You need a service with support and an SLA: the author states there is no support, and enterprise use implies a fork
- You need exact page breaks and sheet PDFs on Linux or macOS: only Excel COM on Windows does that
Example request
Export sales.xlsx to JSON with exstruct, find the tables and show with a dry run how to add a total column without changing the fileLimitations
- A full extraction (shapes, arrows, SmartArt, page breaks, PDF and PNG) needs Excel COM, that is Windows with Excel installed. On Linux and macOS OOXML parsing works and, with LibreOffice, an approximate mode.
- The `libreoffice` mode rejects `--pdf`, `--image` and `--auto-page-breaks-dir`; the `light` mode rejects `--auto-page-breaks-dir`.
- YAML, TOON, rendering and speed-up need extra packages: `pyyaml`, `python-toon`, `pypdfium2` with `pillow`, and `exstruct[fast]`.
- The accuracy benchmark in the repository currently covers 12 cases.
How to disable. Remove the package with `pip uninstall exstruct`. An MCP server launched through `uvx` only needs to be removed from the client configuration, and the `exstruct-cli` skill is deleted with its folder in the skills directory.
FAQ
How do I install ExStruct?
Run `pip install exstruct`. Extras go in square brackets: `exstruct[mcp]` for the MCP server, `exstruct[yaml,toon,render,fast]` for formats, rendering and speed-up.
How do I connect the ExStruct MCP server?
Run `uvx --from 'exstruct[mcp]' exstruct-mcp --root C:\data --log-file C:\logs\exstruct-mcp.log --on-conflict rename`. The `--root` parameter points to the working folder with workbooks. You can pin a version with `exstruct[mcp]==0.4.4`.
How do I install the exstruct-cli skill?
With `npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli`. If `npx skills` is unavailable, put the `.agents/skills/exstruct-cli/` folder into any directory where the agent looks for `SKILL.md` files.
Does ExStruct work without Excel installed?
Yes. The `light` mode reads `.xlsx` and `.xlsm` directly through OOXML. With LibreOffice installed (on Debian and Ubuntu with the `python3-uno` package) `--mode libreoffice` is available too.
How do I change a workbook safely?
Run `exstruct validate`, then `exstruct patch --dry-run` and inspect the `PatchResult`. Pass `--backend openpyxl` so the dry run and the real run use one engine: with `--backend auto` on Windows the real edit may switch to COM.
Discussion
No questions or reviews yet.
Related
CLI toolsExcel MCP Server (negokaz): read and write Excel
Excel MCP Server (negokaz)
An MCP server that reads and writes Excel workbooks: values, formulas, tables, formatting and new sheets; on Windows it can also capture a sheet screenshot
An MCP server to create and edit Excel files without Microsoft Office: formulas, formatting, charts, pivot tables
office-oxide-mcp: Office and PDF for AI agents
office-oxide-mcp
A Rust MCP server that reads and creates Excel, Word, PowerPoint and PDF locally and fills PDF forms after your approval
agent-spreadsheet: Excel for AI agents
agent-spreadsheet
An MCP server, CLI and SDK for agents: read and edit Excel workbooks, recalculate formulas, prove changes without UI automation
A skill plus the docx program: the agent fills forms, edits tables and reviews Word files with tracked changes
MCP Word server for docx editing with tracked changes: comments, footnotes, version comparison and a change log, all visible in Word
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| ExStruct (this card) | no | 203 | ||
| Excel MCP Server | no | not required | 4,292 | an MCP server that creates and edits Excel without Microsoft Office: formulas, formats, charts, pivot tables |
| ExcelMcp | no | not required | 887 | an MCP server and CLI for real Microsoft Excel: Power Query, DAX, VBA, pivot tables |
README in short
The page starts with the features and extraction modes, then covers installation with extras, a quick start for extraction and for editing, and a section on the skill and MCP server with a table of nine tools. Python examples follow, table detection tuning, two demos (tables with a chart and an application form), benchmarks, notes on enterprise use and the project architecture.