slim-sheet

io.github.j4flmaoPublished by GitHub account j4flmaov0.1.0Updated Oct 30, 2026

Spreadsheet MCP for any agent: reads xlsx/xls/ods/csv, SQL, cleaning, formulas, safe edits

VerifiedSTDIODesktop onlyProductivity & WorkflowFiles & StorageData & Analytics

Overview

AI-generated overview

Local MCP server that lets an assistant read, query, clean, edit and format spreadsheet files (xlsx, xls, ods, csv and more) and build branded dashboards.

What you can do
  • Map and read workbooks: overview, read cells with A1 coordinates, find text or regex, describe a cell and trace formulas
  • Query and profile data: read-only SQL SELECT over sheets, column statistics, anomaly checks, file diffs
  • Change data: write values, fill/copy/sort/replace/insert/delete ranges, clean tables, merge, convert or split files, pivot, undo
  • Build and style output: one-call branded dashboards and styled tables, charts, tables, validation and highlight rules, sheet layout and print setup
  • Work with formulas: explain, evaluate offline, what-if and goal seek, recalculate via LibreOffice
  • Manage structure: create workbooks, add/rename/copy/delete sheets, defined names, notes, links and…
When to use it
Useful when an assistant needs to inspect or modify real spreadsheet files on the user's machine without writing Python or openpyxl code, for example auditing a model, cleaning a messy export, reconciling two tables, or producing a client-ready report or dashboard.
Requirements
Runs locally over stdio, started with uvx from the slim-sheet PyPI package, so Python and uv are needed. Optional extras add offline formula evaluation, encrypted workbooks, Apple Numbers and image insertion. LibreOffice is needed only for recalc. Configuration uses environment variables such as SLIM_SHEET_ROOTS, SLIM_SHEET_TIER and SLIM_SHEET_MAX_TOKENS; SLIM_SHEET_PASSWORD is needed for encrypted workbooks.
Before you install
Editing tools write files: by default they save to a new .slim.xlsx copy unless overwrite=true, and undo reverts the last write. SLIM_SHEET_ROOTS controls which folders may be read and written, so scope it narrowly. SLIM_SHEET_PASSWORD is a secret for encrypted workbooks and should be set in the host config, not in chat. Spreadsheet cell text is untrusted data and may contain injected instructions.

Installation

In SourceWeft

  1. Open slim-sheet in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

slim-sheet

A spreadsheet MCP server that small local models can actually use. It reads xlsx xlsm xltx xltm xlsb xls ods numbers csv tsv parquet json locally (no Office, no network), keeps every response under a token budget, and gives agents SQL, cleaning, anomaly detection, a formula copilot, Excel-correct editing and one-call branded dashboards — through 8, 18 or 30 tools depending on how capable the model is.

Works with Claude Desktop / Claude Code (Free or Pro), OpenCode, Codex, Cursor, Cline, Continue, LM Studio, Ollama (via mcpo or Open WebUI) — and as a plain CLI for agents without MCP.

Install

bash
uvx slim-sheet mcp                          # MCP server over stdiouvx slim-sheet overview sales.xlsx          # or use any tool from the shelluvx --from "slim-sheet[all]" slim-sheet mcp # + offline formula engine, encrypted files, Apple Numbers

Host configuration for every client (Claude, Cursor, OpenCode, Codex, LM Studio, Ollama/mcpo, Open WebUI, Cline, Continue) is in docs/hosts.md.

json
{  "mcpServers": {    "slim-sheet": {      "command": "uvx",      "args": ["slim-sheet", "mcp"],      "env": { "SLIM_SHEET_TIER": "lite", "SLIM_SHEET_ROOTS": "/path/to/your/data" }    }  }}

Tiers

TierToolsFor
full (default)every tool belowany model that should be able to do everything
liteoverview, read, find, query, profile, write, explain_formula, build_report3B–8B local models
standardlite + clean, anomalies (+formula audit), merge, convert (+split), diff, undo, evaluate (+check), describe_cell (+trace), style_sheet, what_ifmid-size and frontier models
fullstandard + create_workbook, sheet_ops, range_ops, name_ops, format_range, set_table, rules, add_chart, sheet_layout, annotate, pivot, split, recalcfrontier models building workbooks

Pick exact tools with SLIM_SHEET_TOOLS=overview,read,query.

Design: professional output with almost no description

The model names what to show; slim-sheet decides how it looks — layout, colours, fonts, number formats, chart type, sort order and an insight title — from a brand. One call:

text
build_report(path="sales.xlsx", data_sheet="Sales", title="Sales performance 2025",             kpis=["Revenue=sum:Revenue", "Margin=ratio:Profit/Revenue", "Orders=count"],             charts=["trend:Month:Revenue", "rank:Region:Revenue", "share:Product:Revenue"])

gives a one-page dashboard: KPI tiles with live formulas (7.1m · 20.4% · 144), a line titled "Revenue rose 58% from 2025-01 to 2025-12", a sorted bar with the leader highlighted, a labelled doughnut, a source footer. style_sheet(path, sheet, preset="report") does the same for any table and reports the number formats it inferred.

Your company's look, set once. Built-in brands: slim (default), office, modern (Aptos), mono (IBCS-style), gov (UK government statistics style). Or point SLIM_SHEET_BRAND at a JSON file — only name is required:

json
{ "name": "Acme", "primary": "#C8102E", "body_font": "Arial", "currency": "$", "profile": "finance" }

Every workbook then carries the brand as a real Office theme, so Excel's own table and chart styles follow it too. Rules behind the defaults (IBCS, finance colour coding, UK spreadsheet accessibility guidance, chart-choice tables): PLAN.md §16.

What makes it different

  • Reads everything with one interface, including .xls, .xlsb, .ods, Apple Numbers and password-protected xlsx.
  • Budgeted output: Markdown tables with A1 coordinates, ~1,500 tokens per response, next cursors to continue.
  • Errors that teach: every error has a code, a message and a corrected example call.
  • SQL over sheets with DuckDB; messy sheets are split into regions with detected headers ("Report.2").
  • Never destroys data: edits go to <name>.slim.xlsx unless overwrite=true, writes are atomic, every replaced file is journaled, and undo steps back.
  • Excel-correct structure edits: inserting/deleting rows or renaming a sheet rewrites formulas, names, merges, validations, conditional formats, tables and charts the way Excel does.
  • Model checking: anomalies scope='formulas' finds hardcoded numbers, broken patterns, double counting and where an error starts; describe_cell trace= follows formulas across sheets; what_if runs delta, goal seek and sensitivity grids without touching the file.
  • Formula copilot: 514-function catalog, version checks (XLOOKUP in Excel 2016 → suggests INDEX/MATCH), offline evaluation with dependency chasing.
  • Macros, read-only: read sheet='#vba' shows VBA source, anomalies scope='macros' rates risk, and agents redo a macro's job with tools (prompt replace_macro). slim-sheet never runs macros.
  • Excel-exact formulas: newer functions are stored with Excel's _xlfn. prefixes and spilling formulas as real dynamic arrays, with a warning when something blocks the spill.
  • Flexible paths, safe by default: give any folder in chat (no config change); system folders, AppData, dot-folders such as .ssh and non-spreadsheet files are refused. Read-only SQL with file access locked, no model-written code is executed, no network.

Configuration

VariableDefaultMeaning
SLIM_SHEET_TIERfullfull, standard or lite
SLIM_SHEET_TOOLS—explicit comma-separated tool list
SLIM_SHEET_ROOTScurrent directorydefault folders for relative paths and overview() (; on Windows, : elsewhere)
SLIM_SHEET_STRICT_ROOTSoff1 = only paths inside SLIM_SHEET_ROOTS (the old allow-list)
SLIM_SHEET_MAX_TOKENS1500default response budget
SLIM_SHEET_TOKEN—bearer token for --transport streamable-http (required off loopback)
SLIM_SHEET_PASSWORD—password for encrypted workbooks (never passed through chat)
SLIM_SHEET_SOFFICEautodetectLibreOffice binary for recalc
SLIM_SHEET_AUDIT_LOG—JSONL audit log of every tool call (contents redacted)
SLIM_SHEET_RATE_LIMIT120HTTP tool calls per minute per client (0 = off)
SLIM_SHEET_MAX_CELLS3000000refuse workbooks declaring more cells (0 = off)
SLIM_SHEET_BRANDslimbrand name (slim, office, modern, mono, gov) or path to a brand .json

Extras: formula (offline evaluate and what_if), crypto (encrypted xlsx), numbers (Apple Numbers), images (insert pictures with annotate), all.

Prompt library

Ready-made, data-agnostic prompts — a shared CORE method, thirteen ROLES (nine analyst roles: sales, finance, marketing, customer, operations, HR, reconciliation, data quality, general; plus model auditor, workbook editor, macro migrator and file reviewer) and eight OUTPUT patterns (dashboard, dashboard pack, report workbook, clean dataset, reconciliation report, quick answer, audit report, edited workbook), with filled-in example sets, about 50 one-paste task recipes in 8 packs (finance, sales, HR, operations, data prep, Excel tasks, reporting, Vietnam) and compact blocks for small local models: docs/prompts.

Skill packs

skills/building-client-reports turns the tools into client-ready reports: a report brief, role presets (CFO, board, sales, marketing, operations, HR, market research), a standards checklist and evals. Copy it into ~/.claude/skills/ or attach it to any agent (skills/README.md).

Non-MCP hosts

bash
slim-sheet schema --format openai --tier lite      # function-calling schemas for any OpenAI-compatible APIslim-sheet schema --format anthropic --tier full   # Messages API tool definitionsSLIM_SHEET_TOKEN=... slim-sheet mcp --transport streamable-http --host 0.0.0.0 --port 8765

Development

bash
uv sync --all-extrasuv run pre-commit install                 # ruff, mypy, manifests, commit-message rule, tests on pushuv run python scripts/make_demo.py        # sample workbooks in ~/Documents/slim-sheet-demouv run ruff check . && uv run ruff format --check . && uv run mypy src && uv run pytest -q

Issues and pull requests use the templates in .github/; security reports go through SECURITY.md.

Design and roadmap: PLAN.md · agent rules: AGENTS.md · MIT licensed.

Source: README.md at commit c9e9976

Tools

30

overview

Workbook overview

Map a spreadsheet file (or list the spreadsheets in a folder; no path lists all allowed folders): sheets, used ranges, header row, columns and types. Call this first.

Parameterspath

read

Read cells

Read cells as a table with A1 coordinates (sheet, range 'A1:F50', cursor). sheet='#vba' lists macros; range='Module1' shows its code.

Parameterspathrequiredrangesheetcursorformatmax_tokens

find

Find cells

Find cells containing text (or a regex) across sheets; returns Sheet!A1 addresses. Example: find(path='sales.xlsx', text='refund')

Parameterspathrequiredtextrequiredregexsheetmax_results

query

SQL query

Run one read-only SQL SELECT; tables are sheet names, quote names with spaces. Example: sql='SELECT "Region", sum("Total") FROM "Orders" GROUP BY 1'

Parameterssqlrequiredpathrequiredoffsetmax_tokens

profile

Profile columns

Column statistics for a sheet: type, nulls, distinct, min, max, mean, median, top values. Optional columns list.

Parameterspathrequiredsheetcolumns

write

Write cells

Write a 2-D values array starting at range's top-left cell, e.g. values=[['Total', 120]]. Saves to <name>.slim.xlsx unless overwrite=true.

Parameterspathrequiredrangerequiredsheetrequiredvaluesrequiredout_pathoverwrite

explain_formula

Explain formula

Explain and check an Excel formula: steps, references, syntax/arity errors. Pass formula='=...' or path plus cell like 'Sheet1!C7'.

Parameterscellpathsheetformula

build_report

Build dashboard

Build a branded, print-ready dashboard from a data sheet. Example: kpis=['Revenue=sum:Rev 2025|vs:Rev 2024:2024'], charts=['trend:Month:Total','table:Region:Total'], messages=['finding']

Parameterskpispathrequiredbrandsheettitlerequiredchartsmessagesout_pathsubtitleoverwritedata_sheetrequired

clean

Clean table

Clean a table: ops from trim, collapse_spaces, remove_nonprintable, unify_null, numbers_from_text, normalize_dates, drop_empty_rows, drop_empty_cols, dedupe. Previews unless apply=true.

Parametersopsrequiredkeyspathrequiredapplysheetout_pathoverwrite

anomalies

Find anomalies

Find suspicious cells (duplicates, types, outliers, typos); scope='formulas' audits models; scope='macros' rates VBA risks; scope='client' checks readiness for clients.

Parameterspathrequiredscopesheetcolumnsmax_results

merge

Join or reconcile tables

Join two tables on keys (how=left|inner|full|anti), or how=reconcile to label rows matched/different/only_left/only_right. keys=['ID'] or ['ID=Order No'].

Parametershowkeysrequiredpathrequiredsheetcompareout_pathoverwritetolerancemax_tokensother_pathrequiredother_sheet

convert

Convert or split

Convert to xlsx/csv/tsv/parquet/json by out_path extension; CSV: delimiter=';', encoding='cp1252', decimal=','. split_by='Region' splits; a folder exports VBA.

Parametersmodepathrequiredsheetdecimalencodingout_pathsplit_bydelimiteroverwrite

diff

Compare files

Compare two files cell by cell, or row by row with key='ID'. Example: diff(path='a.xlsx', other_path='a.slim.xlsx')

Parameterskeypathrequiredsheetother_pathrequiredmax_results

undo

Undo last write

Undo the last slim-sheet write to a file (every editing tool is journaled).

Parameterspathrequired

evaluate

Evaluate or check formula

Calculate a formula offline, or check it with check_only=true (target='2016'). Example: evaluate(path='x.xlsx', cell='Calc!C7')

Parameterscellpathsheettargetformulacheck_only

describe_cell

Describe and trace cell

Everything about one cell: value, formula, format, note, validation; trace='precedents' or 'dependents' follows formulas across sheets.

Parameterscellrequiredpathrequireddepthsheettrace

style_sheet

Style table

Make a table look professional in one call: header, number formats, totals, widths, print setup, and restyles the sheet's charts. preset=report|data|finance|striped|minimal|charts.

Parameterspathrequiredbrandrangesheetrequiredpresetout_pathoverwritetotal_rownumber_format

what_if

What-if analysis

Change inputs in memory and see outputs move: op=delta|goal_seek|grid. Example: inputs=['Inputs!B3=8%'], outputs=['Model!B20']. Never writes.

Parametersoppathrequiredsheetinputsrequiredtargetoutputsrequired

create_workbook

Create workbook

Create a new empty branded .xlsx with the given sheet names. Example: create_workbook(path='out.xlsx', sheets=['Data','Summary'])

Parameterspathrequiredbrandsheetsoverwrite

sheet_ops

Sheet operations

Add, rename, delete, copy, move, hide or unhide a sheet (op=...). Renames also fix formulas that point to the sheet.

Parametersoprequiredpathrequiredsheetrequirednew_nameout_pathpositionoverwrite

range_ops

Range operations

Edit a block: op=fill|copy|move|transpose|sort|replace|insert|delete|clear|split. Example: op='fill', range='D2:D200'. where="Status='Closed'" filters rows.

Parametersbyoprequiredtodescfindpathrequiredwhatrangesheetrequiredwhereheaderreplace+5 more

name_ops

Defined names

List, add or delete defined names. Example: name_ops(path, op='add', name='TaxRate', ref='Rates!B2')

Parametersoprequiredrefnamepathrequiredout_pathoverwrite

format_range

Format cells

Style a range: role ('title','header','total'...), bold, colors, number_format ('percent','m'...), align, border, merge, autofit.

Parametersboldpathrequiredrolewrapalignmergerangerequiredsheetrequiredborderitalicvalignautofit+6 more

set_table

Excel table

Turn a range with a header row into a named Excel table; same name again resizes it. Example: set_table(path, sheet='Data', range='A1:D50', name='Sales', totals=true)

Parametersnamerequiredpathrequiredrangerequiredsheetrequiredstyletotalsout_pathoverwrite

rules

Validation and highlight rules

Add a dropdown/input rule (kind=list|whole|decimal|date|text_length|custom) or highlight rule (greater_than|between|duplicates|top_n|color_scale|data_bar|formula...).

Parameterskindrequiredpathrequiredrangerequiredsheetrequiredvaluevalue2valuesformulamessageout_pathoverwritefill_color+2 more

add_chart

Add chart

Insert a clean branded chart (type=auto picks one) from data_range: header row + category column + series columns. Optional highlight='North'; replace=true swaps the chart at anchor.

Parameterspathrequiredtyperequiredbrandsheetrequiredtitleanchorreplacex_titley_titleout_pathhighlightoverwrite+1 more

pivot

Pivot summary

Summarise a table: rows=['Region'], values=['Total'], agg=sum|count|avg|min|max, columns='Month'. to_sheet saves it; native=true makes a real Excel PivotTable.

Parametersaggpathrequiredrowsrequiredsheetnativevaluesrequiredcolumnsout_pathto_sheetoverwritemax_tokens

recalc

Recalculate

Recalculate every formula with LibreOffice so cached values are fresh (needs LibreOffice installed).

Parameterspathrequiredout_pathoverwrite

sheet_layout

Sheet layout

Set how a sheet looks and prints: freeze, widths=['A=14'], heights, filter_range, hide, gridlines, zoom, print_area, landscape, fit_width, protect; workbook: calc_mode, protect_structure.

Parametershidepathrequiredzoomsheetrequiredfreezeunhidewidthsheightsprotectout_pathcalc_modefit_width+6 more

annotate

Notes, links, images

Add a note, hyperlink or image to a cell, or remove objects: op=note|link|image|remove. Example: op='link', cell='B2', url='https://...'

Parametersoprequiredurlcellrequiredpathrequiredtextsheetrequiredtargetout_pathoverwriteimage_path

Version history

1
  1. v0.1.0LatestOct 30, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts