logisheets-mcp

A real spreadsheet engine your agent can think in. Excel-compatible formulas it doesn't have to do in its head, a table it addresses by name instead of by coordinate, and a genuine .xlsx at the end that a person can open, audit and keep using.

An MCP server over LogiSheets, a spreadsheet engine written in Rust. MIT, runs on your machine, opens no sockets.

The trouble with a grid

Ask a model for a five-year projection and it writes twenty formulas, each with the row number adjusted by hand. That is where the silent mistake lives: one of them reads B7 where it meant B8, the total looks plausible, and nothing raises an error.

Then the sheet moves. Someone inserts a row at the top, deletes a year, adds a column. Every coordinate the model was holding is now off by one and it has no way to notice, so it spends the next turns re-reading cells to work out where things went instead of on the question you asked.

And every "what if" costs a round trip — write the input, recalculate, read the output, put it back. Sixteen scenarios is sixteen of those, and a scan that dies half way leaves a scenario behind in your model.

Blocks

A block is a named table on the sheet. Rows have keys, columns have names, and everything is addressed by those rather than by position.

• A field's formula is stated once, for the whole column — not per cell. Add a row and it computes. There is no twentieth formula to get wrong.
• A reference names what it means: the pv field of the row keyed Y3. Insert a row above it and the reference still says the same thing, because it never said "row 8".
• The engine owns computed values. A formula field cannot be overwritten with a number the model worked out itself.

create_block     proj    fields: year, fcf, df, pv
set_field_rule   proj.pv = fcf × df          ← once, for the column
add_block_rows   Y1 … Y5
describe_block   proj
  →  Y1 147.2727   Y2 144.5950   Y3 141.9660   Y4 139.3848   Y5 136.8506

… the sheet is then reshaped: two rows inserted at the top, a column at the left …

describe_block   proj
  →  Y3 141.9660               ← same answer, same address, nothing re-derived

Blocks are created by the agent as it works, so nothing needs preparing. Point it at a blank workbook or at a spreadsheet someone emailed you — convert_to_block adopts a table that is already in ordinary cells, reading the field names off the header row and working out which column is the key.

The second session

The conversation that builds a spreadsheet is almost never the conversation that has to answer a question about it. A week later there is a new session, with none of the context, holding only the file — and what the file records is what that session can know.

A grid records coordinates. =B11*$B$3*(1-$B$4) is correct and means nothing until the agent fetches the label column and infers that A3 describes B3. The schema is where the meaning goes instead, and it is written into the .xlsx: field names, the key column, which fields the engine computes, and the rule behind each one. One list_blocks call and the workbook introduces itself; one describe_block and the rules come back as #FIELD("revenue")*BLOCKREF("assum","margin","v") — an explanation rather than a second lookup problem.

The schema still only says what shape the records are. What they mean is prose, so a block carries a description: a sentence or two on create_block, or set_block_description for a table adopted later, saying what one row is, what the non-obvious fields hold, and what a later reader must not touch. It is stored in the file and comes back from describe_block, which is the difference between the next session reading the intent and inferring it from column names.

src/cold-read.test.ts pins that down rather than asserting it. It builds a model in one session, saves it, and reopens the file in a second session sharing nothing with the first — own server, own workbook, no memory. Then: list_blocks recovers every block's fields, key field, computed fields and row count in one call; every returned rule is checked to contain #FIELD or BLOCKREF and no A1 coordinate at all; the fresh session writes a BLOCKREF formula from orientation alone and the engine agrees with arithmetic done independently in the test; and trace names what reads an assumption before anyone edits it. Cost is metered on the wire, over the same text a host shows the model: 540 B for a five-row model, 545 B for a hundred-and-five-row one, one call each. Reading a schema is O(columns); reading a grid to understand it is O(cells). Asking for the data still costs what the data costs — 11 kB for those 105 rows — and the point is that the second session gets to choose.

Longer version, with the reasoning: docs/the-second-session.md.

Charts that recompute

An agent asked for a chart usually renders an image. The image is right once, and then the human changes an assumption and it is a picture of a number that is no longer true.

chart_from_block writes a chart into the workbook instead, and a chart there stores references, never values:

chart_from_block   rev   value_fields: q1, q2   category_field: region
  →  <c:val><c:numRef><c:f>Rev!$B$1:$B$3</c:f></c:numRef>

That is a native Excel c:chartSpace in the saved .xlsx — the same object Excel writes itself. Edit a source cell and the chart follows, in Excel or here. Add a region to the block and it appears in the chart on its own, because the series is bound to the field, not to the cells the field happened to occupy when the chart was made: inserting rows or columns cannot leave it pointing somewhere wrong. chart_insert does the same for arbitrary A1 ranges, for data that never became a block.

src/agent-loop.test.ts asserts this from the file's bytes rather than from the tool's return value: build a block, chart it, save, unzip the .xlsx and check that the chart part exists and that its series are <c:f> references into the sheet.

Benchmarks

Measured, not asserted. Against the two other MCP servers that work on a local .xlsx — spreadsheet-kit 0.11.1, which has its own Rust recalc engine, and excel-mcp-server 0.1.8, the most-installed one, on openpyxl:

Reproduce it — one file per task, and each one runs all three servers:

npm run build                     # ours is driven as dist/cli.js
python3 bench/t1_compute.py       # bench/t*.py

The other two contestants have to be reachable first: spreadsheet-kit as an amd64 Docker image, excel-mcp-server in a virtualenv at $BENCH_WORK/.venv (default /tmp/bench-work). See bench/contestants.py for exactly how each is started.

The tasks were committed before any other server's tool list was read (bench/TASKS.md), every expected value is derived independently in Python rather than read off a server's output, and tasks we expected to lose are in the list on purpose.

Three caveats, so the table is not read for more than it says. "=SUM(A1:A2)" is not a bug: openpyxl stores formulas without evaluating them, so that server writes correct models but cannot answer a question about one. spreadsheet-kit is a genuine peer, correct on everything it can attempt, and builds the model in fewer calls than we do — our extra calls declare a schema, which is the trade that pays off in the rows below. And on the reading row each server was reading back a file it wrote, so only half of that margin transfers to a spreadsheet that came from a person. The last row started at 0 of 8; writing the task is what found that saves were dropping everything the engine had no opinion about.

Install

Requires Node 20+.

npm install -g logisheets-mcp

For Claude Desktop, add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json), then restart:

{
    "mcpServers": {
        "logisheets": {
            "command": "npx",
            "args": ["-y", "logisheets-mcp"]
        }
    }
}

Any MCP host that spawns a stdio server works the same way — Cursor reads the same block from ~/.cursor/mcp.json.

Try it

Build me a three-year revenue model: 100 units at $9.50 growing 40% a year, with a 30% cost of goods. Then save it to ~/model.xlsx.

The numbers come back from the engine rather than from the model's guesses, and the .xlsx has live formulas in it — change an assumption in Excel and watch it recompute. To see the same thing with no LLM involved, npm run build && npm run demo drives the real server over stdio and checks every claim as it goes.

Tools

Twenty-six by default. Tool-selection accuracy falls as the list grows and every description costs context on every turn.