ExcelMCPAdvanced

Fast, multi-sheet Excel retrieval and writing via the Model Context Protocol. Built on python-calamine for speed; openpyxl only where calamine cannot reach (formula extraction, writing).

---

Tools

Tool	Purpose
excel_list_sheets	List all sheet names in a workbook
excel_get_sheet_size	Get rows × cols — O(1) for .xlsx, O(n) otherwise
excel_get_sheet_full	Read an entire sheet as a markdown table
excel_get_sheet_patches_truncated	Auto-detect data regions (patches), return them truncated with IDs
excel_get_sheet_patches_by_id	Return full data for specific patch IDs
excel_get_sheet_cell_ranges	Return data for explicit A1-notation ranges
excel_write_workbook	Write {sheet: markdown_table} data to an .xlsx file

---

Typical Workflows

Deep analysis (recommended for large files)

excel_list_sheets(file)
→ excel_get_sheet_size(file, sheet)                    # check dimensions first (O(1))
→ excel_get_sheet_patches_truncated(file, sheet)       # get patch IDs + shape
→ excel_get_sheet_patches_by_id(file, sheet, [ids…])   # pull full data for relevant patches

Quick overview

excel_get_sheet_patches_truncated(file, sheet, top_n_patches=5)

Small sheet

excel_get_sheet_full(file, sheet)

Targeted extraction

excel_get_sheet_cell_ranges(file, sheet, ["A1:D20", "G5:J15"])

---

Sheet Size

excel_get_sheet_size returns {rows, cols, cells, method}:

{"sheet_name": "Sales", "rows": 150001, "cols": 12, "cells": 1800012, "method": "xml_dimension_tag"}

Speed:

• .xlsx / .xlsm: reads workbook.xml (~2 KB) + the first 8 KB of the sheet XML to extract the <dimension ref="A1:E150001"/> element. A 200 MB file with 2 million rows takes the same time as a 10-row file.
• .xls / .xlsb / .ods: calamine row iteration — O(n rows) but never loads the full sheet into memory.

---

Patch IDs

A patch is a contiguous rectangular block of non-empty cells, separated from other patches by completely empty rows or columns.

Patch IDs encode their location: {Sheet}_P{n}_{TopLeft}_{BottomRight}

• Example: Sales_P01_A1_E15000, Forecast_P03_B5_BD10
• The bounding box is embedded in the ID, so excel_get_sheet_patches_by_id requires no shared state between calls.

---

Content Modes

Both values and hybrid are supported on all read tools via the content parameter.

Mode	Behaviour
values (default)	Computed cell values. Fast — calamine only.
hybrid	Formula cells show the raw formula (=SUM(A1:A10)); hardcoded cells show values. Slightly slower — requires an extra openpyxl pass.

---

Truncation

excel_get_sheet_patches_truncated truncates large patches to keep context manageable:

| Order ID | Date       | Customer   | ... (truncated 50 cols) | Amount  |
|----------|------------|------------|-------------------------|---------|
| 10001    | 2024-01-01 | Apex Corp  | ...                     | $150.00 |
| 10002    | 2024-01-02 | Beta LLC   | ...                     | $200.00 |
| ...      | ...        | ...        | ... (truncated 14,995)  | ...     |
| 24995    | 2024-12-30 | Charlie Inc| ...                     | $150.00 |
| 24996    | 2024-12-31 | Delta Co   | ...                     | $350.00 |

Control via:

• truncate_top_n — rows/cols shown at head and tail (default 3)
• truncate_threshold — dimension must exceed this to trigger truncation (default 10)

---

Writing

excel_write_workbook accepts a dict of {sheet_name: markdown_table} and coerces cell values:

Input string	Excel type
=SUM(A1:A10)	Formula
42, 3.14	Numeric
TRUE / FALSE	Boolean
15%	0.15 (numeric)
`` (empty)	Blank cell
anything else	String

---

Installation

git clone <repo>
cd Excel-MCP-Server-Advanced
python -m venv .venv && source .venv/bin/activate
pip install -e .

Supported formats: .xlsx, .xls, .xlsb, .ods (read); .xlsx (write).

---

MCP Client Configuration

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "excel": {
      "command": "/path/to/.venv/bin/excel-mcp-server"
    }
  }
}

---

Development

# Generate test workbook
python tests/create_test_excel.py

# Run tests
python tests/test_tools.py