SheetForge MCP

Local-first Excel MCP server for AI agents that need structured reads, workbook introspection, and safer.xlsxmutation.

SheetForge MCP is an Excel MCP server for.xlsxautomation over the Model Context Protocol. It is built for AI agents, MCP clients, and automation workflows that need more than raw cell access: compact structured reads, workbook-aware guidance, layout-aware inspection, and safer write paths with Python andopenpyxl, without launching Microsoft Excel or LibreOffice.

If you are looking for an Excel MCP server for spreadsheet automation, workbook inspection, Excel report generation, dashboard authoring, or.xlsxediting from AI tools, SheetForge MCP is built for that workflow.

Instead of treating every sheet as a blind cell grid, SheetForge helps agents distinguish native Excel tables, worksheet-shaped datasets, layout-heavy dashboards, and chart sheets, then choose the right read or mutation path for each workbook task.

Package name:sheetforge-mcpCLI command:sheetforge-mcpPublished package release:0.8.0Repository docs track the current main-branch tool surface, which currently exposes76MCP tools.

- agent-friendly reads viasuggest_read_strategy,describe_dataset,query_table, andaggregate_table
- safer workbook creation:create_workbooknow refuses to overwrite an existing.xlsx
- smarter worksheet boundaries so compact readers stop at the main contiguous data block and surface trailing-row hints instead of over-reading sparse footer noise
- workbook and layout awareness viaprofile_workbook,describe_sheet_layout,list_tables,list_charts, andanalyze_range_impact
- safer local mutation throughdry_run, compact write responses, guarded native-table append/upsert flows, and workbook diff/audit/repair loops
- local-first performance and privacy withopenpyxl, no desktop Excel dependency, and no cloud-auth requirement

- workbook creation and metadata
- worksheet creation, renaming, copying, deletion, and visibility
- structured reads, compact table reads, declarative table queries, grouped aggregates, and cell search
- row, column, and range mutations
- formulas and validation checks
- formatting, freezes, autofilters, merges, and conditional formatting
- native Excel tables, charts, and pivot summaries
- stdio,streamable-http, and deprecatedssetransports

- AI agents that need safe, structured Excel workbook access through MCP
- spreadsheet automation workflows that read and update.xlsxreports
- Excel dashboard generation with formatting, tables, charts, freeze panes, and print setup
- workbook QA and inspection flows that need metadata, named ranges, tables, charts, and protection state
- data extraction from native Excel tables or worksheet-shaped datasets without hand-writtenopenpyxlscripts

- Python3.10+
- .xlsxworkbooks
- eitheruvxor a local package install

Install and run directly from PyPI withuvx, or install the package locally in your Python environment.

Usestdiowhen the MCP client starts the server locally.

{ "mcpServers": { "excel": { "command": "uvx", "args": ["sheetforge-mcp", "stdio"] } } }

Usestreamable-httpwhen you want a long-running local or remote server process.

EXCEL_FILES_PATH=/path/to/excel-files uvx sheetforge-mcp streamable-http

{ "mcpServers": { "excel": { "url": "http://127.0.0.1:8017/mcp" } } }

SSE is kept for compatibility, but new integrations should preferstreamable-http.

EXCEL_FILES_PATH=/path/to/excel-files uvx sheetforge-mcp sse

- Instdiomode,filepathvalues must be absolute paths.
- Instreamable-httpandssemode, relative paths are resolved underEXCEL_FILES_PATH.
- Absolute paths are accepted in every transport.
- Instreamable-httpandssemode, the server createsEXCEL_FILES_PATHautomatically if it does not exist.

The server currently registers 76 MCP tools across these groups:

- workbook overview:create_workbook,create_worksheet,get_workbook_metadata,profile_workbook,describe_sheet_layout,audit_workbook,plan_workbook_repairs,apply_workbook_repairs,diff_workbooks,analyze_range_impact,explain_formula_cell,detect_circular_dependencies,create_named_range,inspect_named_range,list_named_ranges,delete_named_range,list_all_sheets,list_tables
- data access:suggest_read_strategy,describe_dataset,query_table,aggregate_table,bulk_aggregate_workbooks,bulk_filter_workbooks,union_tables,cross_workbook_lookup,quick_read,read_excel_table,read_data_from_excel,read_excel_as_table,search_in_sheet,write_data_to_excel,append_table_rows,append_excel_table_rows,upsert_excel_table_rows,update_rows_by_key
- worksheet and range changes:copy_worksheet,delete_worksheet,rename_worksheet,set_worksheet_visibility,get_worksheet_protection,set_worksheet_protection,copy_range,delete_range,insert_rows,insert_columns,delete_sheet_rows,delete_sheet_columns
- formatting and layout:format_range,format_ranges,read_range_formatting,freeze_panes,set_autofilter,set_print_area,set_print_titles,set_column_widths,autofit_columns,set_row_heights,merge_cells,unmerge_cells,get_merged_cells
- formulas and validation:apply_formula,validate_formula_syntax,inspect_formula,validate_excel_range,get_data_validation_info,inspect_data_validation_rules,remove_data_validation_rules,inspect_conditional_format_rules,remove_conditional_format_rules
- analysis and structure:create_table,list_charts,find_free_canvas,create_chart,create_chart_from_series,create_pivot_table

For chart authoring, prefercreate_chartas the primary entry point:

- usedata_rangefor the simple contiguous-data path
- use explicitseriesplus optionalcategories_rangefor non-contiguous or hand-authored charts
- use top-levelwidthandheightto control chart size in centimeters; defaults are15 x 7.5
- useplacementwhen you want SheetForge to position the chart relative to worksheet content, a source range, or a named table instead of guessingtarget_cellmanually
- useplacement={"relative_to": "free_canvas"}when a busy dashboard needs the first non-overlapping chart slot instead of a simple right/below placement rule
- keepcreate_chart_from_seriesfor backward compatibility or existing prompts that already rely on it

- suggest_read_strategy: recommends the best next read tool for a workbook target, including whether SheetForge should treat it as a native Excel table, a clean worksheet dataset, a layout-heavy dashboard sheet, or a chart sheet
- describe_dataset: samples a worksheet or native Excel table and returns headers, schema hints, key-candidate guesses, structural signals, and a recommended follow-up read path
- query_table: filters, projects, sorts, and limits worksheet-shaped data or native Excel tables with a declarative JSON query instead of ad hoc cell loops
- aggregate_table: computes grouped metrics such ascount,sum,avg,min, andmaxover worksheet-shaped data or native Excel tables
- bulk_aggregate_workbooks: computes the same grouped metrics across many workbook files in one call, with explicit schema handling viastrict,intersect, orunion
- bulk_filter_workbooks: returns matching rows across many workbook files with optional source provenance columns, so recurring cross-file QA and reporting checks no longer need one-tool-call-per-file loops
- union_tables: combines comparable worksheet or native-table rows across many workbook files, with optional deduplication keys and explicit schema handling for workbook collections that drift over time
- cross_workbook_lookup: enriches one workbook dataset from one or more lookup workbooks with left-join style matching, optional duplicate-match handling, and compact per-row provenance for matched lookup rows
- profile_workbook: one-call inventory for sheets, tables, charts, named ranges, and key layout/protection state, including chartoccupied_rangefor grid-anchored worksheet charts
- describe_sheet_layout: worksheet-level structural summary for safe dashboard edits, including freeze panes, print settings, merges, chart anchors, table metadata, conditional-format and validation counts, custom row/column sizing, and a small free-canvas preview
- audit_workbook: workbook-level audit for high-signal problems such as broken#REF!formulas, error cells, hidden sheets, header-quality issues, layout-heavy sheets, and named ranges that reference missing sheets
- plan_workbook_repairs: converts workbook audit findings into prioritized next steps, including suggested SheetForge tool calls for inspection, safe dry runs, and repair workflows
- apply_workbook_repairs: dry-runs or applies the safe repair subset from those plans, including broken named ranges, broken validation rules, broken conditional formats, and optional hidden-sheet reveals
- diff_workbooks: compares two workbook files and reports structural changes plus sampled cell-value diffs, which is useful for before/after verification in agent workflows
- analyze_range_impact: preflight blast-radius check for a worksheet range, including overlaps with tables, chart footprints, merged cells, named ranges, data validations, conditional formats, autofilters, print areas, formula cells inside the range, and formulas or rule expressions elsewhere that depend on it directly or transitively, through named ranges, or through structured table references such asTable1[Sales]
- explain_formula_cell: resolves a formula cell's direct references, shows upstream formula-chain cells, returns a compactformula_chainsummary with depth layers and sampled paths, and reports downstream dependents so agents can debug workbook logic without manual tracing
- detect_circular_dependencies: scans workbook formula graphs, including named-range-driven edges, and reports self-references plus multi-cell circular dependency groups before they surprise downstream automation
- create_named_range: creates workbook-level or sheet-scoped named ranges withdry_runandreplacesupport, so agents can promote important workbook regions into stable references without dropping to ad hoc Python
- inspect_formula: inspects a formula string without workbook context, listing functions, reference token types, volatile functions, and risky functions such asINDIRECT
- inspect_named_range: inspects one defined name, including its scope, destinations, and whether it points at missing sheets or broken references
- quick_read: single-call compact table read that auto-selects the first sheet when needed, now withstart_rowpagination andstart_col/end_colcolumn windowing for large sheets
- read_excel_table: read a native Excel table bytable_namewithout guessing worksheet bounds, now withstart_rowpagination and optionalstart_col/end_coltable column windowing
- list_all_sheets: quick workbook inventory with sheet sizes, emptiness flags, andsheet_typefor worksheets versus chart sheets
- read_excel_as_table: compactheaders + rowsoutput for structured datasets, withcompact=Truefor the smallest payload,start_rowfor page-like reads, andstart_col/end_colfor narrower column slices
- read_data_from_excel: cell-address-aware range reader that supportsmax_rowsandmax_colswindowing for large non-tabular ranges,values_only=Truefor smaller 2D payloads, and cursor-based continuations for multi-step 2D traversal
- read_range_formatting: compact formatting readback for a worksheet range, grouped by distinct style signatures instead of noisy per-cell dumps, with merged-range and conditional-format overlap summaries
- search_in_sheet: exact or partial value search across a worksheet

Workbook inventory tools such aslist_all_sheets,profile_workbook, andlist_chartssurface both worksheets and chart sheets. Grid-oriented tools such asquick_read,read_excel_table,create_table, formatting, formulas, and validation require a real worksheet and return a clear chartsheet error if you target the wrong sheet type.

The most agent-friendly write helpers for structured data are:

- upsert_excel_table_rows: update matching rows in a native Excel table and append missing keys in one call Note: totals-row tables are update-only for now; append attempts are rejected rather than shifting unrelated rows.
- append_excel_table_rows: append rows to a native Excel table when you want the tablerefto grow with the new records
- append_table_rows: append header-aware rows to worksheet-shaped data when you do not have a native Excel table
- update_rows_by_key: update worksheet-shaped data by a named key column without appending missing keys

For the compact table readers (quick_read,read_excel_as_table,read_excel_table):

- row_mode="arrays"keeps the smallestheaders + rowsshape
- row_mode="objects"returnsrecordskeyed by normalized field names such asfirst_name
- normalized field names are ASCII-safe transliterations, so headers likeNäyttökerratbecomenayttokerrat
- infer_schema=Trueadds lightweightschemahints inferred from the returned rows
- start_col/end_collet you slice wide worksheets or native Excel tables down to just the columns you need before pagination or schema inference
- truncated pages now includenext_start_row, which you can pass back to the same tool for the next page
- non-tabular range reads can also returncontinuations.downandcontinuations.rightcursor tokens so agents can continue large 2D windows without recomputing coordinates
- suggest_read_strategyhelps agents choose between table-aware, worksheet-aware, range-aware, and workbook-orientation reads before they spend context on the wrong path
- describe_datasetprovides a lighter-weight dataset summary than a full read, including sample rows, header quality, key candidates, and recommended next tool
- describe_dataset,quick_read,read_excel_as_table, andread_excel_tablenow also returnstructure_token,content_token, andsnapshot_metadata, so agents can carry read-time identity forward into safer optimistic-concurrency writes
- worksheet-shaped compact readers and row-mutation helpers favor the first contiguous data block after the header, so sparse footer notes or distant outlier rows do not silently stretchtotal_rows, append targets, or key-based update scans
- describe_datasetnow surfacesdata_end_rowandignored_trailing_row_countwhen later non-empty rows are treated as a separate block below a large blank gap
- query_tableis the lightest way to pull just the matching rows and columns you need from a worksheet dataset or native Excel table
- query_tableandbulk_filter_workbooksacceptneas a shorthand forneq, and membership filters can use eithervaluesor the shortervaluelist form
- aggregate_tablelets agents compute grouped summaries directly in SheetForge instead of over-reading the full dataset into context first
- bulk_aggregate_workbooksextends that pattern across many workbook files when a recurring reporting workflow would otherwise need ad hoc Python or repeated per-file tool calls
- aggregate metrics accept both the canonical{"op": "sum", "field": "Sales", "as": "total_sales"}shape and the more guessable alias form{"agg": "sum", "column": "Sales", "as": "total_sales"}
- bulk_filter_workbooksdoes the same for row-level inspection, while keeping workbook provenance visible by default
- union_tablesis the fastest way to normalize many comparable workbook datasets into one combined tabular payload before downstream QA, export, or further aggregation
- cross_workbook_lookupis the fastest way to enrich one workbook from another without writing an ad hoc merge script, especially for master-data lookups, status enrichment, and cross-file QA workflows
- append_excel_table_rowsis the right append path for native Excel tables when you do not need key-based upsert behavior
- append_table_rowsnow refuses to write directly under an adjacent native Excel table and points you atappend_excel_table_rowsinstead of silently leaving the table range stale
- token-aware structured writes can passexpected_structure_tokento abort on structural drift; append-style writes additionally requireallow_structure_change=True, and successful writes report both previous and new structure/content tokens
- rename_worksheetnow updates formula cells as well as chart references and named ranges, and it also renames the default sibling pivot sheet (Data_pivot->Revenue_pivot) when that move is conflict-free
- formatting color inputs acceptRRGGBB,#RRGGBB,AARRGGBB, or#AARRGGBB, so prompts do not need to strip CSS-style#prefixes first
- audit_workbookis the fastest workbook-wide preflight when you need to know whether a spreadsheet is safe and predictable enough for autonomous editing
- audit_workbooknow treats dominant native-table sheets more honestly when nearby dashboard/layout artifacts extend the used range, so unrelated merged/chart areas do not create false blank-header risk on an otherwise clean table
- plan_workbook_repairsis the fastest way to turn those audit findings into an actual action queue instead of manually deciding the next tool call for every problem
- apply_workbook_repairslets agents preview or apply the safe subset of those repairs without having to orchestrate each broken workbook artifact manually
- diff_workbooksis the quickest before/after QA pass when an agent has touched workbook structure and wants proof of what actually changed
- Unfamiliar workbook -> safe mutation -> verification Start withlist_all_sheetsorprofile_workbook, inspect layout-heavy tabs withdescribe_sheet_layout, runanalyze_range_impactbefore overwriting an important range, then confirm the before/after result withdiff_workbooks.
- Workbook repair loop Useaudit_workbookto find high-signal issues,plan_workbook_repairsto turn them into an action queue,apply_workbook_repairs(..., dry_run=True)to preview the safe subset, then rerunaudit_workbookafter applying repairs to confirm the workbook is back to a low-risk state.
- Multi-workbook reporting Usebulk_aggregate_workbooks,bulk_filter_workbooks,union_tables, orcross_workbook_lookupto build the reporting dataset first, then write the summarized rows into a fresh workbook tab and finish the presentation layer withformat_ranges,find_free_canvas,create_chart, andautofit_columns.

SeeTOOLS.mdfor the full reference. Release notes live inCHANGELOG.md.

{ "ok": true, "operation": "read_excel_as_table", "message": "read_excel_as_table completed", "data": {} }

{ "ok": false, "operation": "write_data_to_excel", "error": { "type": "DataError", "message": "No data provided to write" } }

Sync Calendars, Scheduling Links, AI Executive Scheduling Assistant, Unified Calendar