MCP + Excel

SheetForge MCP

An Excel MCP server for AI agents and automation workflows that need to read, write, search, format, validate, chart, and restructure `.xlsx` workbooks with `openpyxl`.

Use SheetForge MCP when you want spreadsheet automation, workbook inspection, Excel report generation, dashboard updates, or workbook-safe mutation planning over the Model Context Protocol without launching desktop Excel.

Published package release: 0.7.0. The repository currently exposes 75 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, workbook diffs, formula-lineage debugging, formula-string inspection, circular-dependency detection, native-table appends and upserts, compact mutation responses, grouped formatting readback, sheet-layout summaries, cursor-based 2D range reads, placement-aware chart authoring, and workbook-level impact analysis for formulas, validations, and conditional formatting.

View Repository Tool Reference Changelog

At a glance

  • Python 3.10+
  • 75 MCP tools
  • 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`
  • Relative file root: `EXCEL_FILES_PATH` in HTTP and SSE modes

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.
  • `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.
  • `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 in one workbook pass.
  • `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 before safe mutations
  • 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

Client config example

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