MCP + Excel

SheetForge MCP

A local-first Excel MCP server for AI agents and automation workflows that need structured reads, workbook introspection, and safer `.xlsx` mutation with `openpyxl`.

Use SheetForge MCP when raw cell access is not enough: it can profile workbooks, distinguish tables from layout-heavy sheets, query and aggregate worksheet data, inspect formulas, and plan safer edits before writing.

Published package release: 0.9.0. The repository currently exposes 77 MCP tools, including smart read-strategy suggestions, lightweight dataset summaries, declarative table queries, grouped aggregates, cross-workbook aggregation, cross-workbook filtering, cross-workbook unions, cross-workbook lookups, workbook profiling, repair planning and execution, verified workbook snapshots, workbook diffs, formula-lineage debugging, formula-string inspection, circular-dependency detection, named-range creation, native-table appends and upserts, guarded worksheet-boundary presets, compact mutation responses, grouped formatting readback, sheet-layout summaries, cursor-based 2D range reads, placement-aware chart authoring, workbook rename sync for formulas and default pivot sheets, and workbook-level impact analysis for formulas, validations, and conditional formatting.

View Repository Tool Reference Changelog

At a glance

  • Python 3.10+
  • 77 MCP tools
  • Smart dataset summaries and read-strategy guidance
  • Supports `stdio`, `streamable-http`, and deprecated `sse`
  • Uniform JSON envelopes for every tool response
  • No Microsoft Excel dependency
  • Backed by `openpyxl` and FastMCP

Transport defaults

  • Host: `127.0.0.1`
  • Port: `8017`
  • HTTP endpoint: `/mcp`
  • SSE endpoint: `/sse`
  • File sandbox: all HTTP/SSE paths stay inside `EXCEL_FILES_PATH`
  • Remote bind: explicit opt-in plus external authentication boundary required

Best starting tools

  • `list_all_sheets`
    Quick workbook overview before reading.
  • `profile_workbook`
    One-call workbook inventory with tables, charts, filters, print settings, and protection state.
  • `audit_workbook`
    Workbook-wide preflight for broken references, hidden sheets, header issues, and layout-heavy tabs.
  • `plan_workbook_repairs`
    Turn audit findings into a prioritized SheetForge repair and inspection queue.
  • `apply_workbook_repairs`
    Dry-run or apply safe workbook cleanup actions with audit summaries and structural diffs.
  • `diff_workbooks`
    Compare workbook versions and sample the actual before/after cell-value changes.
  • `create_workbook_snapshot`
    Create a verified, non-overwriting baseline before risky workbook edits.
  • `explain_formula_cell`
    Trace a formula cell through named ranges, structured references, upstream formula cells, compact formula-chain layers and sampled paths, and downstream dependents.
  • `detect_circular_dependencies`
    Find self-referential and multi-cell formula cycles before they break downstream calculations or agents.
  • `inspect_formula`
    Inspect a formula string for functions, reference token types, volatile functions, and risky patterns.
  • `query_table`
    Filter, sort, and trim worksheet-shaped data or native tables before it reaches agent context.
  • `aggregate_table`
    Compute grouped metrics directly in SheetForge instead of post-processing full reads.
  • `bulk_aggregate_workbooks`
    Roll up comparable workbook files with explicit `strict` / `intersect` / `union` schema handling.
  • `bulk_filter_workbooks`
    Pull matching rows across workbook files with source provenance visible by default.
  • `union_tables`
    Combine comparable workbook datasets into one row set, with optional dedupe keys for "latest row per ID" style workflows.
  • `cross_workbook_lookup`
    Enrich one workbook from lookup workbooks with left-join style matching, duplicate-match controls, and per-row lookup provenance.
  • `quick_read`
    Single-call compact table read with automatic first-sheet selection and guarded boundary presets.
  • `read_excel_table`
    Read a native Excel table by name without guessing worksheet bounds.
  • `read_data_from_excel`
    Read non-tabular ranges with compact payloads and cursor-based continuations.
  • `analyze_range_impact`
    Inspect blast radius before edits, including formulas, validation rules, and conditional formatting.
  • `create_chart`
    Create charts from either contiguous ranges or explicit series definitions.
  • `format_ranges`
    Apply batch formatting across multiple areas with range-level rollback on failure.
  • `autofit_columns`
    Fit columns to content without hand-tuning widths.
  • `search_in_sheet`
    Find a value before mutating a workbook.
  • `upsert_excel_table_rows`
    Update matching rows in a native table and append missing keys in one call.
  • `append_table_rows`
    Append rows with header names instead of cell math.
  • `update_rows_by_key`
    Update existing rows by matching a key column.

Quick start

uvx sheetforge-mcp stdio

Best fit

  • AI agents that need structured Excel access through MCP
  • `.xlsx` report automation without hand-written workbook scripts
  • Workbook profiling, audit, and diff workflows before safe mutations
  • Local spreadsheet workflows where privacy, low latency, and token efficiency matter
  • Excel dashboards with tables, charts, formatting, freeze panes, and print setup

Streamable HTTP example

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

Loopback-only by default. Remote binding requires explicit opt-in and an external authenticated network boundary.

Client config example

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