# Spreadsheet Mcp

> MCP server for spreadsheet analysis and editing. Slim, token-efficient tool surface designed for LLM agents.

- **Type:** MCP server
- **Install:** `agentstack add mcp-psu3d0-spreadsheet-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [PSU3D0](https://agentstack.voostack.com/s/psu3d0)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.10.1
- **License:** Apache-2.0
- **Upstream author:** [PSU3D0](https://github.com/PSU3D0)
- **Source:** https://github.com/PSU3D0/spreadsheet-mcp

## Install

```sh
agentstack add mcp-psu3d0-spreadsheet-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# spreadsheet-kit

[](https://github.com/PSU3D0/spreadsheet-mcp/actions/workflows/ci.yml)
[](https://crates.io/crates/spreadsheet-mcp)
[](https://www.npmjs.com/package/agent-spreadsheet)
[](https://github.com/PSU3D0/spreadsheet-mcp/blob/main/LICENSE)

**spreadsheet-kit is the tool interaction service for agent-based spreadsheet usage.**

It gives agents a safe, inspectable, token-efficient way to **read, analyze, mutate, verify, and operationalize Excel workbooks** without falling back to brittle UI automation.

If you want an agent to work with spreadsheets like a real system instead of a screenshot puppet, this is the stack.

---

## What this project is

spreadsheet-kit ships a unified spreadsheet interaction layer across four surfaces:

| Surface | Binary / Package | Mode | Best for |
| --- | --- | --- | --- |
| **CLI** | `asp` / `agent-spreadsheet` | Stateless | One-shot reads, safe edits, pipelines, CI, agent tool calls |
| **MCP server** | `spreadsheet-mcp` | Stateful | Multi-turn agent sessions, workbook caching, fork/recalc workflows |
| **JS SDK** | `spreadsheet-kit-sdk` | Backend-agnostic | App integrations that can target MCP today and WASM/session backends over time |
| **WASM runtime** | `spreadsheet-kit-wasm` | In-process | Experimental byte/session embedding for local runtimes |

Supported workbook modes:

- `.xlsx` / `.xlsm` — read + write
- `.xls` / `.xlsb` — discovery/read-oriented workflows only

---

## Why agents use spreadsheet-kit

### Built for tool use, not just humans
- deterministic JSON contracts
- schema and example discovery from the CLI itself
- explicit pagination and compact output modes
- machine-readable warnings and error envelopes

### Safe mutation, not blind mutation
- dry-run first workflows
- stateless output modes and overwrite safety
- event-sourced session editing
- verification surfaces for proving downstream outcomes
- structural impact analysis before risky workbook changes

### Spreadsheet-aware, not generic file editing
- region detection
- table and footer-aware append helpers
- template row / row band cloning
- formula-specific replace and diagnostics
- named range CRUD
- recalculation + diff + proof flows

### Good agent ergonomics
- nested command groups with legacy alias compatibility
- token-efficient reads
- exact-cell inspection and layout inspection
- workflow helpers for the repetitive parts agents usually get wrong

---

## What is new / what makes this stack different

The current surface is much stronger than a plain “read some cells” tool. Major capabilities now include:

- **`asp` as the primary CLI** with `agent-spreadsheet` preserved as a compatibility alias
- **grouped verification** via `asp verify proof` and `asp verify diff`
- **preview-first workflow helpers** for:
  - `write append`
  - `write clone-template-row`
  - `write clone-row-band`
- **formula-safe batch workflows** with parse-policy diagnostics
- **cell/layout/export/import inspection surfaces**
- **named range management** (`write name define|update|delete`)
- **formula-only replacement** (`write formulas replace`)
- **event-sourced session editing** with log, branch, undo/redo, fork, apply, and materialize
- **SheetPort manifest lifecycle + execution** for contract-driven spreadsheet automation

---

## Install

### npm (recommended for CLI)

```bash
npm i -g agent-spreadsheet
asp --help
```

Installs both:
- `asp` — primary command
- `agent-spreadsheet` — compatibility alias

Downloads a prebuilt native binary for your platform. No Rust toolchain required.

### Cargo

```bash
# CLI
cargo install spreadsheet-kit --features recalc --bin asp --bin agent-spreadsheet

# MCP server
cargo install spreadsheet-mcp
```

Formualizer (the native Rust recalc engine) is included by default.

### Docker

```bash
# Read-only / slim
docker pull ghcr.io/psu3d0/spreadsheet-mcp:latest

# Write + recalc + screenshots
docker pull ghcr.io/psu3d0/spreadsheet-mcp:full
```

### JavaScript SDK

```bash
npm i spreadsheet-kit-sdk
```

### Prebuilt binaries

Download from [GitHub Releases](https://github.com/PSU3D0/spreadsheet-mcp/releases).

Published native assets include:
- Linux x86_64
- macOS x86_64
- macOS arm64
- Windows x86_64

---

## Start here: the core workflows

## 1) Orient the workbook before reading cells

```bash
# What sheets are here?
asp read sheets data.xlsx

# What regions/tables/parameter blocks does this sheet contain?
asp read overview data.xlsx "Model"

# What named items are available?
asp read names data.xlsx

# Read a structured region as a table
asp read table data.xlsx --sheet "Model"
```

## 2) Inspect exactly what an agent needs

```bash
# Raw values for exact ranges
asp read values data.xlsx Model A1:C20

# Detail-view for targeted cells (value / formula / cached / style triage)
asp read cells data.xlsx Model B2 D10:F12

# Layout-aware rendering for a bounded range
asp read layout data.xlsx Model --range A1:H30 --render both

# Export a bounded range to csv or grid json
asp read export data.xlsx Model A1:H30 --format csv --output model.csv
```

## 3) Do a safe stateless edit → recalc → proof → diff loop

```bash
asp workbook copy data.xlsx /tmp/draft.xlsx
asp write cells /tmp/draft.xlsx Inputs "B2=500" "C2==B2*1.1"
asp workbook recalculate /tmp/draft.xlsx
asp verify proof data.xlsx /tmp/draft.xlsx --targets Summary!B2,Summary!B3 --named-ranges
asp verify diff data.xlsx /tmp/draft.xlsx --details --limit 50
```

A representative label-mode lookup:

```bash
asp analyze find-value data.xlsx "Net Income" --mode label --label-direction below
```

## 4) Preview structural risk before mutating the workbook

```bash
asp analyze ref-impact data.xlsx --ops @structure_ops.json --show-formula-delta
```

This is intentionally read-only. It surfaces shifted spans, absolute-reference warnings, token counts, and optional before/after formula samples.

## 5) Use workflow helpers instead of reinventing row logic

```bash
# Stateless batch writes
asp write batch transform data.xlsx --ops @ops.json --dry-run
asp write batch style data.xlsx --ops @style_ops.json --dry-run

# Append rows into a detected region or table, respecting footer rows when present
asp write append data.xlsx --sheet Revenue --table-name RevenueTable --from-csv rows.csv --header --dry-run

# Clone one template row with preview-first planning
asp write clone-template-row data.xlsx --sheet Inputs --source-row 8 --after 8 --count 3 --dry-run

# Clone a contiguous row band repeatedly
asp write clone-row-band data.xlsx --sheet Forecast --source-rows 12:16 --after 16 --repeat 4 --dry-run
```

## 6) Use a stateful session when the edit story gets complex

```bash
asp session start --base data.xlsx --workspace .
asp session op --session  --ops @edit.json --workspace .
asp session apply --session   --workspace .
asp session materialize --session  --output result.xlsx --workspace .
```

And when you need proper history and branching:

```bash
asp session log --session  --workspace .
asp session fork --session  scenario-a --workspace .
asp session undo --session  --workspace .
asp session redo --session  --workspace .
asp session checkout --session   --workspace .
```

## 7) Turn workbook interfaces into contracts with SheetPort

```bash
# Discover candidate ports from workbook structure
asp sheetport manifest candidates model.xlsx

# Validate or normalize a manifest
asp sheetport manifest validate manifest.yaml
asp sheetport manifest normalize manifest.yaml

# Bind-check a workbook against a manifest
asp sheetport bind-check model.xlsx manifest.yaml

# Execute the manifest with JSON inputs
asp sheetport run model.xlsx manifest.yaml --inputs @inputs.json
```

---

## CLI overview

The primary CLI is **`asp`**.

`agent-spreadsheet` remains available as a compatibility alias, so both of these are valid:

```bash
asp read sheets data.xlsx
agent-spreadsheet read sheets data.xlsx
```

### Preferred command groups

- `asp read ...`
- `asp analyze ...`
- `asp write ...`
- `asp workbook ...`
- `asp verify ...`
- `asp session ...`
- `asp sheetport ...`

### Legacy aliases

Legacy flat commands are still normalized to the new nested surface where practical. That makes migration easier for older prompts, docs, and automation.

### Discoverability built into the CLI

When an agent is unsure of payload shape, it can ask the tool directly:

```bash
asp schema write batch transform
asp example write batch transform
asp schema session op transform.write_matrix
asp example session op transform.write_matrix
```

This is a core design principle: **the surface should explain itself to the agent**.

---

## Command families

## `read` — extraction and inspection

| Command | Purpose |
| --- | --- |
| `asp read sheets ` | List sheets with summary metadata |
| `asp read overview  ` | Detect regions, headers, and orientation |
| `asp read values    [range...]` | Pull raw values for exact A1 ranges |
| `asp read export   ` | Export a bounded range to csv or grid json |
| `asp read cells    [target...]` | Inspect exact cells/ranges with value/formula/cached/style snapshots |
| `asp read page   ...` | Deterministic sheet paging with `next_start_row` |
| `asp read table  ...` | Structured table/region read with deterministic `next_offset` |
| `asp read names ` | Named ranges, named formulas, and table items |
| `asp read workbook ` | Workbook-level metadata |
| `asp read layout  ` | Layout-aware rendering with widths, merges, borders, and optional ascii output |

### Why these matter for agents

Agents rarely need “the whole spreadsheet.” They need:
- the right region
- the right page
- the right cells
- just enough layout to understand intent

That is why the read surface combines **region detection**, **structured reads**, **detail inspection**, and **explicit continuation**.

---

## `analyze` — search, diagnostics, and impact understanding

| Command | Purpose |
| --- | --- |
| `asp analyze find-value  ` | Search by value or by label semantics |
| `asp analyze find-formula  ` | Text search within formulas |
| `asp analyze formula-map  ` | Summarize formulas by complexity/frequency |
| `asp analyze formula-trace    ` | Dependency tracing with continuation |
| `asp analyze scan-volatiles ` | Find volatile formulas |
| `asp analyze sheet-statistics  ` | Density and type statistics |
| `asp analyze table-profile ` | Header/type/cardinality profiling |
| `asp analyze ref-impact  --ops @structure_ops.json` | Preflight structural edit impact without mutation |

### Why this matters

Headless spreadsheet automation wins when it can **explain consequences**, not just execute mutations. `ref-impact`, `formula-trace`, and grouped diagnostics are all part of that story.

---

## `write` — safe mutations and workflow helpers

| Command | Purpose |
| --- | --- |
| `asp write cells   ...` | Direct shorthand cell edits |
| `asp write import   ...` | Import grid json or csv into a workbook range |
| `asp write append ...` | Footer-aware row append into a region or table |
| `asp write clone-template-row ...` | Clone one template row with preview-first planning |
| `asp write clone-row-band ...` | Clone a multi-row template band repeatedly |
| `asp write formulas replace ...` | Formula-only find/replace on a sheet/range |
| `asp write name define|update|delete ...` | Named range mutation helpers |
| `asp write batch transform ...` | Stateless transform pipeline |
| `asp write batch style ...` | Stateless style edits |
| `asp write batch formula-pattern ...` | Autofill-like formula application |
| `asp write batch structure ...` | Rows/cols/sheets/copy/move style mutations |
| `asp write batch column-size ...` | Column width operations |
| `asp write batch sheet-layout ...` | Freeze panes, zoom, page setup, print area |
| `asp write batch rules ...` | Data validation + conditional formatting |

### Safety model

Most mutating commands support a strict mode matrix:
- `--dry-run`
- `--in-place`
- `--output `

This matters for agents because it allows:
- dry-run planning
- non-destructive execution
- explicit overwrite control

### Formula maintenance

Formula mutation is now a first-class surface:

```bash
asp write formulas replace data.xlsx Sheet1 --find '$64' --replace '$65' --dry-run
asp write formulas replace data.xlsx Sheet1 --find 'Sheet1!' --replace 'Sheet2!' --range A1:Z100 --output fixed.xlsx
```

### Named range maintenance

```bash
asp write name define data.xlsx RevenueInput 'Inputs!$B$2'
asp write name update data.xlsx RevenueInput 'Inputs!$B$2:$B$4' --in-place
asp write name delete data.xlsx RevenueInput --in-place
```

---

## `workbook` — file-level flows

| Command | Purpose |
| --- | --- |
| `asp workbook create ` | Create a new workbook |
| `asp workbook copy  ` | Safe copy for edit workflows |
| `asp workbook recalculate ` | Recalculate formulas via the configured backend |

---

## `verify` — proof, not vibes

| Command | Purpose |
| --- | --- |
| `asp verify proof  ` | Prove target deltas and isolate new/resolved/preexisting errors |
| `asp verify diff  ` | Summary-first grouped workbook diff with optional paged details |

### Why verification matters

Most spreadsheet automation tools stop at “the edit applied.”

spreadsheet-kit goes further:
- did the target cells change the way we expected?
- did the workbook introduce new errors?
- which changes were direct edits vs recalculation fallout?
- what changed overall, grouped in a way an agent can reason about?

This verification layer is a big part of why this project is a serious agent substrate rather than a utility script.

---

## `session` — event-sourced stateful editing

The session surface is for workflows that are too complex for a single stateless write.

### What sessions give you
- persistent editing state
- staged dry-run operations
- compare-and-swap apply semantics
- logs and replayability
- branch/switch/fork flows
- undo / redo / checkout
- explicit materialization back to a workbook file

### Canonical loop

```bash
asp session start --base model.xlsx --workspace .
asp session op --session  --ops @ops.json --workspace .
asp session apply --session   --workspace .
asp session materialize --session  --output result.xlsx --workspace .
```

### History and branching

```bash
asp session log --session  --workspace .
asp session branches --session  --workspace .
asp session fork --session  experiment-b --workspace .
asp session switch --session  experiment-b --workspace .
asp session undo --session  --workspace .
asp session redo --session  --workspace .
asp session checkout --session   --workspace .
```

Use sessions when you want **repeatability, auditability, and multi-step safety**.

---

## `sheetport` — spreadsheet interfaces as executable contracts

SheetPort is the workflow surface for turning workbook inputs/outputs into explicit machine contracts.

### Manifest lifecycle

```bash
asp sheetport manifest candidates model.xlsx
asp sheetport manifest schema
asp sheetport manifest validate manifest.yaml
asp sheetport manifest normalize manifest.yaml
```

### Bind-check + run

```bash
asp sheetport bind-check model.xlsx manifest.yaml
asp sheetport run model.xlsx manifest.yaml --inputs @inputs.json --freeze-volatile
```

Use this when you want a workbook to behave less like an opaque file and more like a **declared service interface**.

---

## Output contracts for agents

### Canonical vs compact shapes

All commands default to JSON. Many also support:

```bash
--shape canonical
--shape compact
```

Policy:
- **canonical** keeps the full stable schema
- **compact** removes wrapper noise where the contract allows it while preserving continuation fields and command-specific semantics

Shape policy:
- **Canonical (default):** preserve the full response schema.
- **range-values:** returns a stable `values: [...]` envelope in both canonical and compact modes.
- **range-values default encoding:** dense JSON (`dense.encoding = "dense_v1"`) with `dictionary` + run-length `row_run

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [PSU3D0](https://github.com/PSU3D0)
- **Source:** [PSU3D0/spreadsheet-mcp](https://github.com/PSU3D0/spreadsheet-mcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.10.1 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.10.1** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-psu3d0-spreadsheet-mcp
- Seller: https://agentstack.voostack.com/s/psu3d0
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.