logisheets-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| LOGISHEETS_MCP_TOOLS | No | Set to 'full' to enable the full set of 50 tools (undo/redo, formatting, merges, comments, checkpoints, block move/resize, cross-block links, raw row/column structure). By default, only the core 20 tools are available. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
A real, Excel-compatible spreadsheet engine you can compute in and remember in.
Four things it is for:
Arithmetic you should not do yourself. Write a formula and let the engine evaluate it —
eval_formulafor a one-off, or store the formula in a cell so it keeps recalculating.Structured memory that survives the whole task. A block is a named table; you address its cells by (block name, row key, field name), never by A1 coordinates. Inserting rows never breaks a reference, so you can keep building without tracking where anything sits.
Summaries the engine derives, not ones you compute.
create_analysis_blockadds a totals row under a table;create_pivotcross-tabulates it into one number per group. You declare the recipe — which fields, which function — and the engine generates every formula, so the summary survives a field being renamed and follows rows being added. Do not read a table into your context to add it up; the answer you would write down is a constant, and it is wrong as soon as the next row lands.Charts that stay live.
chart_from_blockplots a block by field name and the chart follows the data — rows added later appear on their own. Never draw a picture of the numbers; make the workbook hold the chart, so it redraws when the human changes an assumption in Excel.
Everything derived is still a block, so a total or one cell of a pivot is addressable with BLOCKREF and can feed the next calculation. One caveat, and it matters: a pivot's numbers are live but its shape is not — rows and columns for values that appear later do not add themselves. describe_block says when a pivot has fallen behind; refresh_pivot fixes it. A stale pivot shows correct numbers with whole groups missing, which is not something you can spot by looking.
The loop: list_blocks to see what you have, create_block to open a structured workspace, add_block_rows / set_block_cells to fill it, formulas for the math, describe_block to read results back, save_workbook to hand the human a real .xlsx.
Prefer blocks over raw cells. get_cells / set_cells exist for data that genuinely has no structure.
Write down what a block is for — a sentence on create_block, or set_block_description afterwards. describe_block gives it back, so it is what the next session (yours or someone else's) reads instead of guessing the meaning from column names.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
| resources | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| open_workbookA | Start the workbook you will work in. Call with no arguments for a fresh, empty one; pass This replaces whatever workbook the session currently holds, discarding unsaved changes — so call it once at the start, not between steps. You do NOT have to call it at all: an empty workbook appears automatically the moment any other tool touches the session. Prefer |
| save_workbookA | Write the workbook to a real .xlsx file the human can open in Excel. This is how you hand your work back — do it when the task is done. Defaults to the path it was opened from, or last saved to; pass IMPORTANT — if the human is going to work on this in Excel, pass The result carries a link to the workbook rather than its bytes, so the host can offer the human the file without any of it passing through your context. |
| export_xlsxA | Return the workbook as base64-encoded .xlsx bytes. Last resort. The bytes land in your context and cost roughly 1.4 KB of text per KB of file. Prefer |
| list_blocksA | Orient yourself in a workbook: every sheet, every block, and for each block the fields you can reference. One call is enough to start writing formulas. Per block you get its ref name (BLOCKREF's first argument), its Use Omit |
| describe_blockA | Return a block's full structure for the LLM: identity (name, sheet, position), per-field schema, and row keys in order. Every field reports both what it IS — Read a field's
Pass |
| eval_formulaA | Evaluate an Excel-style formula in a private scratch cell and return the computed value. Nothing is written to user-visible cells. Returns
Use for:
Leading "=" is optional — it is added automatically if missing. |
| create_blockA | Create a structured block (table) on a sheet. fields[0] is the row-key column — the value BLOCKREF matches on, so it has to be unique per record; it is ordinary data you can write. Block ref name ( Field types supported:
Rules (value_formula / validation / editability) are set separately via set_field_rule — this call only declares structure + initial rows. Auto-creates the target sheet if missing. |
| convert_to_blockA | Turn a table that already exists in ordinary cells into a block, in place, without touching its values. This is how you adopt a workbook someone hands you. Give The row key is inferred: the first column whose values are all present and all different. Pass Converting is a one-time cost: the block and its schema survive saving and reloading, and afterwards the region behaves exactly like one created as a block. |
| set_block_descriptionA | Write what a block is for, in prose, onto the block itself. Saved in the file and returned by describe_block, so it is how the next agent — or the next you, in a later session — learns what the table means.
Say what one row represents, what any non-obvious field holds, and anything that must not be done to it. Do not restate the field names; they are already visible.
Refused when the block reserves |
| add_block_rowsA | Add rows to an existing block. Appends at the end by default; pass after_key or before_key to insert at a position instead. Each row needs a key; values is an object keyed by field name. Fields with a value_formula are auto-materialized by the engine — don't pass them in values. Validation/editability shadows for the new rows are auto-installed by the engine at InsertRowsInBlock time, so no follow-up is needed. Also inserts the matching sheet rows (one block per sheet-row assumption — extends the sheet so downstream rows shift down). |
| delete_block_rowsA | Delete rows from a block by their key. Missing keys are silently ignored. Also deletes the matching sheet rows (one block per sheet-row assumption). If you try to delete every row, the last one is kept and its cells are cleared instead — the engine doesn't allow rowCnt=0 blocks. |
| move_block_rowA | Reorder a block by moving one row to a new position, addressing both the row and its destination by key. Moves to the end when neither after_key nor before_key is given (same default as add_block_rows). Row order inside a block is presentation only — formulas address rows by key, so reordering never changes a single computed value. Use it to match a reading order someone expects, not to change the model. |
| set_block_cellsA | Write one or more cells inside any block(s) in a single atomic transaction. Each change addresses a cell by (block ref name, row_key, field) — the LLM never deals with raw (sheet, row, col). Pass Rejected up-front (whole tx aborts) when any change:
Value can be a literal (string / number / boolean) or a formula prefixed with '='. |
| set_field_ruleA | Attach declarative rules to a field. All three rule kinds (value_formula, validation, editability) are optional — pass only the ones you want to change. Omit a kind entirely to leave it untouched on this field; pass Placeholders supported in formulas: #FIELD("name") — the same row's cell in field "name" #FIELD("name", "key") — field "name" on the row carrying that key, in THIS SAME block #KEY — the row's key value (quoted as a string literal) #PLACEHOLDER — the cell itself (validation/editability only) The two-argument #FIELD is the only way to reach another row of the cell's own block: BLOCKREF is refused there (it depends on the whole-block vertex, so it would close a cycle). Use it for share-of-total or index-to-a-base-row columns, e.g. "=#FIELD("amt")/#FIELD("amt","TOTAL")". The other row is named by KEY, never by position — there is no "previous row" form, because rows can be reordered and inserted into, so a positional address would silently come to mean a different row. A running total (each row reading the row above) therefore has no rule form; write that column as ordinary cells outside the block. A rule that resolves onto the cell it is defining is rejected, as is a plain coordinate (A1/C3) landing inside the block — in a template a coordinate does not shift per row, so on the first row it would point at the cell being defined. Engine behaviour after this call:
Leading "=" on the formula body is optional; omit or include either way. |
| create_analysis_blockA | Add a block that analyses another one — a totals row, sitting directly below the table it summarises. It is an ordinary block that declares which block it analyses, so its result is addressable like any other: What the engine does with the declaration: it GENERATES each field's formula from it, so renaming a field of the source rebuilds the total instead of breaking it, and the total tracks the source as rows are added. Do not write the formulas yourself. By default every Read it back with describe_block: the analysis reports |
| edit_analysis_blockA | Change what an existing analysis block computes: which of the source's fields it aggregates, with which function, and the label its row is addressed by. Use this to arrive at an analysis in STEPS. Summing every number is often nearly right and wrong in one column — a rate wants AVERAGE, a text column wants COUNTA, an id column wants nothing at all. Adjust rather than rebuild: the block keeps its ref name, so formulas pointing at it keep working, and it is one undo.
This is the simple kind of analysis: one row, one number per column. For one number per GROUP, use build__create_pivot / build__edit_pivot instead. |
| create_pivotA | Cross-tabulate a table: one row per distinct value of The result is an ordinary block, so every cell is addressable: You declare the recipe; the engine generates every cell from it. Do not write formulas, and do not write into the block — renaming a field of the source rebuilds the pivot rather than breaking it, which is only true because nothing is hand-written.
IMPORTANT: a pivot's numbers are live but its SHAPE is not. When new values appear in the source, its rows and columns fall behind while every number in it stays correct — call build__refresh_pivot. describe_block reports when that has happened. |
| edit_pivotA | Change an existing pivot's recipe — what it groups by, what it measures, how, in what order, over which records — and reshape it to match. Use this rather than deleting and recreating: the block keeps its ref name, so every formula pointing at it keeps working, and the whole change is one undo. This is also the way to REPAIR a pivot whose recipe stopped resolving (describe_block reports Everything you omit is UNCHANGED. What you pass replaces that part outright — |
| refresh_pivotA | Bring a pivot's rows and columns back in line with its source. Its NUMBERS were never stale — they are live formulas. Only the set of rows and columns falls behind, because no formula can add a row. That is exactly why this matters: a stale pivot shows correct numbers with whole groups missing, and totals taken from it are short with nothing to say so. Call it before reading or reporting a pivot that describe_block flagged. Safe and cheap to call when nothing has changed — it reports that it did nothing. |
| create_sheetA | Create a new sheet in the workbook. Returns the new sheet index. Idempotent: if a sheet with the same name exists, returns its index without creating a duplicate. Typically the agent does NOT call this directly — |
| get_cellsA | Read the values (and formulas) in a rectangular range of cells, addressed by zero-based (sheetIdx, startRow, startCol, endRow, endCol). Returns only the non-empty cells, each with its A1 ref, value, and formula (if any). Use this for ordinary "what is in these cells" questions; for a single computed result you can also use build eval_formula. Reads at most 500 cells per call — narrow the range if it is bigger. |
| set_cellsA | Write one or more arbitrary cells on a sheet in a single atomic transaction (one undo step). Each cell is addressed by zero-based row/col. Content is a literal (string / number / boolean) or a formula prefixed with '='. null or '' clears the cell. For cells that belong to a block, prefer edit set_block_cells (it respects the schema); use this for plain, non-block cells. At most 200 cells per call. |
| list_violationsA | Scan validation shadow cells and return every cell whose validation formula currently evaluates FALSE. Validation is advisory — the cell still holds its value, but the host UI renders a warning marker and you should treat it as "something the user/AI got wrong". A field's rule is what its DECLARATION implies — Also returns Also returns Use this when answering 'why is something red?', 'what's broken after my last edit?', or before quoting any number you did not just compute yourself. It is the one call that answers 'is anything here untrustworthy' — the alternative is describe_block on every block, which is easy to skip and easy to forget. Filters compose: omit both Pull-based on purpose: the LLM is turn-based, polling at decision points is cheaper than maintaining a live subscription. The host UI has its own per-cell push subscription for canvas warning markers. |
| list_namesA | List the workbook's defined names (named ranges and named constants). Each has a name and what it refers to, sheet-qualified (e.g. "Sheet1!$B$2:$B$20" or "0.08"). A formula can use any of them as a reference: =SUM(Sales). |
| preview_changesA | Dry-run edits on the workbook's temp branch and report what they would do. Nothing is committed — the branch is discarded, so this is the safe way to explore a model instead of changing it and putting it back. Two shapes. Add |
| traceA | Follow a cell's dependencies, in either direction, using the engine's own dependency graph.
Both by default. Name the cell semantically as (block, row_key, field), or by coordinate as (row, col) with an optional sheet_idx. Results come back named the same way whenever the cell sits inside a block, so you get "assumptions.wacc" rather than a coordinate to interpret. This asks the engine rather than reading formula text, so it sees through BLOCKREF, ranges and whole-column references, and it answers the reverse direction — which formula strings cannot. Granularity matters when blocks are involved. The engine tracks block dependencies per (block, field), not per row, so |
| goal_seekA | Find the input value that makes a chosen output equal a target — "what discount rate gives a value per share of 30". Runs entirely on the engine's temp branch, so the workbook is never modified: this is a question, not an edit. The search happens inside the engine rather than as a conversation, so it costs one tool call instead of one per iteration. Name both cells semantically as (block, row_key, field) or by coordinate as (row, col). Give Bisection, so it needs the output to move monotonically between the bracket ends and it finds one crossing. If the bracket does not straddle the target it says so rather than returning a number — a non-answer you can act on beats a plausible one you cannot. |
| chart_from_blockA | Chart a block by naming its fields, instead of working out which cells they occupy.
The chart stays bound to the block: it plots whatever the named fields hold, so records added to the block later appear on their own and inserting rows or columns cannot leave it pointing at the wrong cells. A col-schema block works the same way as a row-schema one.
Use |
| chart_insertA | Insert a chart that reads its values live from the given ranges — editing those cells later updates the chart.
Look at the data first so the series are right: a column of labels belongs in categoriesRef, each column of numbers is one series, and its header is that series' name.
References are A1 (B2:B10, or Sheet2!B2:B10 to read another sheet). The chart is placed below the data unless |
| chart_listA | List the charts on a sheet — id, kind, title, the ranges each series reads, and where the chart sits. Call this before updating or deleting one. |
| chart_updateA | Reconfigure an existing chart in place, keeping its position. Anything left out keeps its current value; an empty string clears a text field (title, axis title, number format). Get the chart_id from chart__list first. |
| chart_deleteA | Delete a chart. Get the chart_id from chart__list. Undoable, but it removes the chart and its formatting. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 32 tools
The set is large and has several near-neighbour pairs — create_block vs convert_to_block vs create_analysis_block, set_block_cells vs set_cells, get_cells vs describe_block(include_rows) vs eval_formula, save_workbook vs export_xlsx, create_sheet vs the implicit sheet creation in create_block — but every one of these boundaries is explicitly spelled out in the descriptions ('prefer set_block_cells for block cells', 'prefer save_workbook over export_xlsx', 'typically the agent does NOT call create_sheet'). A few remain softer (list_blocks vs describe_block, list_violations vs per-block validation), so an agent could still occasionally pick the coarser tool when the finer one was intended.
Overwhelmingly a verb_noun snake_case pattern (open_workbook, create_block, add_block_rows, set_field_rule, edit_pivot), with chart_delete the one clear inversion against chart_insert/chart_list/chart_update. Descriptions also cross-reference tools by namespaced aliases that do not exist in the surface (chart__list, build__create_pivot, edit__describe_block, inspect), which muddies predictability even though the underlying convention is stable.
At 32 tools this is well past the comfortable range, and the surface spans five or six distinct concerns (workbook I/O, sheets, blocks/fields, analysis blocks, pivots, charts, what-if analysis). Each tool does appear to earn its place — there is little redundancy — but the cognitive and context cost is high and pushes toward the 'heavy' band rather than a well-scoped set.
The modelling core is strong: blocks can be created, converted, described, populated, re-keyed, reordered, ruled and analysed, and pivots/charts/what-if are all covered. But lifecycle gaps are real — there is no way to delete a whole block (only delete_block_rows), no sheet delete/rename/reorder beyond create_sheet, no way to author a defined name (list_names is read-only), and no cell/sheet formatting or sorting surface. These aren't trivial workarounds for an agent asked to clean up or restructure a workbook.