spreadsheet-mcp

Stateful MCP server for spreadsheet analysis and editing. Part of the spreadsheet-kit workspace.

Install

cargo install spreadsheet-mcp

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

Or use Docker:

# Read-only (~15 MB)
docker pull ghcr.io/psu3d0/spreadsheet-mcp:latest

# With write/recalc (~800 MB, includes LibreOffice)
docker pull ghcr.io/psu3d0/spreadsheet-mcp:full

Quickstart

Stdio (MCP clients)

spreadsheet-mcp --workspace-root /path/to/workbooks --transport stdio

Add to Claude Code / Claude Desktop (~/.claude.json or .mcp.json):

{
  "mcpServers": {
    "spreadsheet": {
      "command": "spreadsheet-mcp",
      "args": ["--workspace-root", "/path/to/workbooks", "--transport", "stdio"]
    }
  }
}

HTTP

spreadsheet-mcp --workspace-root /path/to/workbooks
# → http://127.0.0.1:8079 — POST /mcp

Docker (with write/recalc)

docker run -v /path/to/workbooks:/data -p 8079:8079 \
  ghcr.io/psu3d0/spreadsheet-mcp:full

What this crate provides

• 50+ MCP tools — read-only analysis, VBA inspection, fork-based editing, recalculation, screenshots
• LRU workbook cache — configurable capacity, lazy sheet metrics
• Region detection — automatic identification of tables, parameters, and output blocks
• Token-dense output — sparse JSON by default, pagination only when needed
• Fork lifecycle — create, edit, checkpoint, recalculate, diff, save
• Recalc backends — Formualizer (default) or LibreOffice (feature: recalc-libreoffice, Docker :full)

Binaries

Configuration

Key flags (all have SPREADSHEET_MCP_ env equivalents):

--workspace-root <DIR>       Workspace directory (default: cwd)
--transport stdio|http       Transport mode (default: http)
--cache-capacity <N>         LRU cache size (default: 5)
--recalc-enabled             Enable write/recalc tools
--vba-enabled                Enable VBA inspection tools
--output-profile <P>         token-dense (default) or verbose

See the full configuration reference in the root README.

Related crates

Full documentation

See the root README for the complete tool surface, deployment guide, Docker configuration, write tool shapes, and agent workflow recommendations.

License

Apache-2.0 — see LICENSE.