Docs / CLI options and limits
CLI options and limits.
The server is one binary with two commands. Everything below applies to every host, since each host just launches gridpath mcp on stdio.
Commands
gridpath mcp [--allow <dir> ...] [--review-required] [--port <n>]
gridpath review <file.xlsx> [--port <n>]Run it with npx -y gridpath … to fetch the published package on first use, or install it globally with npm install -g gridpath.
Flags for gridpath mcp
| Flag | Meaning |
|---|---|
--allow <dir> [<dir> …] | Only open files under these folders. Repeat the flag or list several paths after it; ~/, $HOME and %USERPROFILE% are expanded. Default: your home directory. A file outside the allowed folders is refused with a message telling the agent not to copy it elsewhere. |
--review-required | The agent cannot save. save_workbook returns the review link and the user accepts and saves from the review page. save_workbook with as still writes a copy. Also set by GRIDPATH_REVIEW_REQUIRED=true, which is how the Claude Desktop bundle passes its checkbox. |
--port <n> | Port for the local review server. Default: a random free port. |
On startup the server prints one line to stderr with the allowed folders, the review server address, and whether review is required. Stdout is the MCP protocol channel and nothing else is written there.
gridpath review
Starts a review server for one workbook's pending batches, prints the batch count and URL, and opens the page in your browser. Use it to pick up a review after the agent's session has ended. It keeps serving until you press Ctrl-C.
Where state lives
- Pending batches:
<workbook folder>/.gridpath/<file>.batches.json, written after every change and cleared on save. Add.gridpath/to your ignore files if the workbook sits in a repository. - The workbook: untouched until
save_workbookor Save on the review page. - The review server: loopback only, one random token per process, carried in the review URL. Requests from a non-loopback origin are refused.
Supported files
.xlsx and .xlsm. Verified on real analyst models, including a 1.4 MB, 12-sheet, 55,000-formula workbook with 76 package parts, 75 of them byte-identical after an edit, and a 13-sheet .xlsm whose vbaProject.bin came back byte-identical. Charts, pivots, macros, add-in data and custom XML are preserved, not authored: the agent cannot create or edit a chart or pivot. .xls and .csv are not supported.
Limits
| What | Limit |
|---|---|
read_range | 500 cells per call. The reply sets truncated beyond that. |
query_rows | 50 rows or groups by default, 500 maximum, with matched giving the full count. |
find_rows | 20 matches by default. |
run_script | 5 seconds of CPU, 20,000 written cells, 100 log entries of 4,000 characters. |
| Write readback | The first 200 touched cells are returned. |
| Formatting | Cell borders cannot be set in this version. |
| Engine | AGGREGATE, GETPIVOTDATA, HYPERLINK, GROUPBY and PIVOTBY evaluate to #NAME? in the server. They are stored as written and Excel evaluates them on open. |
Requirements
Node 20 or newer on macOS, Windows or Linux. No Python, no Excel, no LibreOffice. The Claude Desktop bundle includes its own Node.
License
FSL-1.1-Apache-2.0. Each release becomes Apache 2.0 two years after it ships. Source: github.com/pixelsmasher13/gridpath.
Found a mistake? Open an issue or email support@gridpath.dev.