🤔 The Problem

Ask your assistant to review a requirements spec. Half the meaning lives in screenshots, flowcharts, and annotated diagrams pasted into cells — and every Excel MCP server hands the model text only. The answer comes back confident and incomplete, because the model never knew the pictures existed.

The same blind spot applies to the other signals authors leave behind:

Same file. One agent sees a table of strings; the other sees what the author actually meant.

✨ Key Features

Image Extraction — What Makes This Different

Most Excel MCP servers only read cell values. This server uses a dual extraction strategy:

1. Cell-Position Mapping (primary) — Maps each image to its exact cell location using openpyxl-image-loader
2. Archive Scanning (fallback) — Scans the xlsx ZIP archive's xl/media/ directory to catch any images missed by method 1

The result: zero images left behind, with position metadata when available.

👀 See It In Action

A requirements spec where the workflow lives in a pasted diagram and the status lives in cell colors:

You: Review this spec and tell me which features are still in scope, and how the dispatch flow works.

read_full_content returns the sheet as text with formatting markers, then the embedded diagram as an image:

Row 1: A1: Feature [B] [HL:blue] | B1: Status [B] [HL:blue]
Row 2: A2: Vehicle dispatch  | B2: Approved [HL:green]
Row 3: A3: Legacy CSV export [S] | B3: Cancelled [S]
Row 4: A4: Driver roll call  | B4: Needs review [HL:yellow]

ℹ️ Skipped 3 hidden row(s) with content. Pass include_hidden=true to read them.

**[Image 1]** Sheet: `Spec` | Cell: `B12` | Original: 1180×840px
[the actual flowchart, as ImageContent]

The model can now answer both halves of the question: "Legacy CSV export is struck through and marked cancelled, so three features remain in scope — and the flowchart in B12 shows dispatch requires roll-call confirmation before assignment."

Without image support, the second half is unanswerable. Without formatting, the cancelled row looks identical to the active ones.

🚀 Quick Start

Install via uvx (Recommended)

No installation needed — runs directly:

uvx excel-vision-mcp

Install via pip

pip install excel-vision-mcp

Then run:

excel-vision-mcp

Install from source

git clone https://github.com/VOYAGER-Inc/excel-vision-mcp.git
cd excel-vision-mcp
uv sync
uv run excel-vision-mcp

Run with Docker

docker build -t excel-vision-mcp .
docker run --rm -i -v /path/to/spreadsheets:/data excel-vision-mcp

The server speaks JSON-RPC over stdin/stdout, so it must run attached (-i). Mount the directory holding your files and reference them by their in-container path (/data/report.xlsx). The image sets EXCEL_VISION_MCP_ALLOWED_DIRS=/data, so reads and writes stay inside the mount.

As an MCP client config:

{
  "mcpServers": {
    "excel-reader": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/spreadsheets:/data", "excel-vision-mcp"]
    }
  }
}

🔧 Configuration

Add the server to your MCP client's configuration file.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"]
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"]
    }
  }
}

Windsurf / VS Code (Copilot)

Edit your MCP settings file:

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"]
    }
  }
}

Antigravity IDE

Edit ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"]
    }
  }
}

Note: After editing the config, restart your IDE/client to load the new server.

Restricting file access (optional)

By default the server can read/write any Excel file your user account can access. To sandbox it to specific directories, set EXCEL_VISION_MCP_ALLOWED_DIRS (multiple paths separated by : on macOS/Linux, ; on Windows):

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"],
      "env": {
        "EXCEL_VISION_MCP_ALLOWED_DIRS": "/Users/me/Documents/spreadsheets:/Users/me/Projects/data"
      }
    }
  }
}

🛠️ Available Tools

list_sheets

List all sheets with dimensions, merged cell counts, and image totals. Use this first to understand a workbook's structure.

list_sheets(file_path="/path/to/file.xlsx")

Returns: Sheet names, row×column dimensions, data ranges, merged cell counts, total image count.

read_excel_data

Read cell data from a specific sheet with pagination support.

read_excel_data(
    file_path="/path/to/file.xlsx",
    sheet_name="Sheet1",      # optional, defaults to first sheet
    start_row=1,              # optional, 1-indexed
    max_rows=200,             # optional, default 200
    include_hidden=False      # optional, read hidden rows/columns too
)

Returns: Cell values organized by row with coordinate labels and markers for merged cells and formatting.

Row 1: A1: Feature [B] [HL:blue] | B1: Status [B] [HL:blue]
Row 3: A3: Legacy export [S] | B3: Cancelled [S]
Row 4: A4: Report | B4: Needs review [HL:yellow] | C4: Urgent [B] [C:red]

Markers and a short legend appear only on sheets that actually use formatting, so plain sheets cost no extra context.

extract_images

Extract all embedded images from the workbook as base64 ImageContent.

extract_images(
    file_path="/path/to/file.xlsx",
    sheet_name="Overview",    # optional, None = all sheets
    max_width=1024,           # optional, resize limit
    max_height=1024           # optional, resize limit
)

Returns: List of ImageContent (base64) with metadata — cell position, sheet name, original dimensions.

read_full_content ⭐

The star tool. Reads ALL text data AND all embedded images in a single call. Ideal for comprehensive document analysis.

read_full_content(
    file_path="/path/to/file.xlsx",
    max_rows_per_sheet=500,   # optional
    max_image_width=1024,     # optional
    max_image_height=1024     # optional
)

Returns: Complete workbook contents — every sheet's data as structured text (with formatting markers), followed by every embedded image with cell-position mapping.

Example use case: "Analyze this requirements document and summarize all use cases, including the workflow diagrams."

Hidden rows & columns

All read tools skip hidden rows and columns by default — an author who hid them signalled they aren't part of the content to review.

One exception: a hidden cell that a visible formula references is still returned, marked [HIDDEN-REF], because its value drives results you can see. Skipped content is always reported so nothing disappears silently:

ℹ️ Skipped 2 hidden row(s) with content. 1 hidden cell(s) are shown anyway
   because visible formulas reference them. Pass include_hidden=true to read them.

Pass include_hidden=true to read_excel_data, read_full_content, or search_excel to read everything.

get_workbook_overview

Quick structural summary of a workbook — file size, sheet list, dimensions, image count.

get_workbook_overview(file_path="/path/to/file.xlsx")

search_excel

Case-insensitive text search across all cells in the workbook.

search_excel(
    file_path="/path/to/file.xlsx",
    query="revenue",
    sheet_name="Q4 Report"    # optional, None = all sheets
)

Returns: Matching cells with sheet name, coordinate, and value. Limited to 100 results.

create_excel_file

Create a new empty workbook with the sheets you name.

create_excel_file(
    file_path="/path/to/new.xlsx",
    sheet_names=["Summary", "Detail"],  # optional, default ["Sheet1"]
    overwrite=False                     # optional, refuses to replace by default
)

add_excel_sheet

Add a new empty sheet to an existing workbook.

add_excel_sheet(file_path="/path/to/file.xlsx", sheet_name="Q3", position=0)

update_excel_cells

Set individual cells by coordinate. Values starting with = are written as formulas.

update_excel_cells(
    file_path="/path/to/file.xlsx",
    updates={"A1": "Title", "B2": 42, "C2": "=SUM(B2:B10)"},
    sheet_name="Data"             # optional, defaults to first sheet
)

Note: newly written formulas show no calculated value until the file is opened in Excel. For merged ranges, write to the top-left anchor cell.

write_excel_rows

Write a rectangular block of tabular data in one call.

write_excel_rows(
    file_path="/path/to/file.xlsx",
    rows=[["Item", "Qty"], ["Widget", 4], ["Gadget", 7]],
    sheet_name="Data",            # optional
    start_cell="A1"               # optional
)

insert_excel_image

Insert a local image file into a workbook, anchored at a cell.

insert_excel_image(
    file_path="/path/to/file.xlsx",
    image_path="/path/to/chart.png",
    cell="B2",
    sheet_name="Report",          # optional
    width=480, height=320         # optional display size in px
)

format_excel_cells

Style a range: font, colors, borders, alignment, number formats. Only the attributes you pass are changed — existing styling is preserved.

format_excel_cells(
    file_path="/path/to/file.xlsx",
    cell_range="A1:D1",
    bold=True,
    font_color="FFFFFF",
    fill_color="4472C4",
    horizontal_align="center",
    border_style="thin",          # thin | medium | thick | double | dashed | dotted
    border_edges="all",           # "all" or "outline" (outer edge of range only)
    number_format="#,##0.00"      # any Excel format code
)

set_excel_column_widths

Set column widths manually and/or auto-fit to content.

set_excel_column_widths(
    file_path="/path/to/file.xlsx",
    widths={"A": 12, "B": 35},    # explicit widths (skipped by auto-fit)
    auto_fit=True,                # size remaining columns to content
    max_width=60,                 # cap for auto-fit
    wrap_overflow=True            # wrap cells longer than the cap
)

Auto-fit counts full-width CJK characters (日本語) as 2 units. Cells longer than max_width get wrap text enabled instead of stretching the column — Excel auto-expands their row heights on open.

All write tools use atomic saves: the workbook is written to a temp file and swapped into place, so a failed save never corrupts your original. .xlsm macros are preserved. Known openpyxl limitation: pivot tables and some complex chart features are not preserved on re-save.

⚙️ How It Works

Architecture

Your AI Client (Claude, Cursor, etc.)
       │
       │ stdio (JSON-RPC)
       ▼
┌─────────────────────────────┐
│     Excel Vision MCP        │
│                             │
│  ┌───────────────────────┐  │
│  │   openpyxl            │  │──→ Cell data, formulas, merged cells
│  │   (Excel parser)      │  │
│  └───────────────────────┘  │
│                             │
│  ┌───────────────────────┐  │
│  │ openpyxl-image-loader │  │──→ Images with cell positions
│  │ + zipfile (fallback)  │  │
│  └───────────────────────┘  │
│                             │
│  ┌───────────────────────┐  │
│  │   Pillow              │  │──→ Resize, optimize, base64 encode
│  │   (image processing)  │  │
│  └───────────────────────┘  │
└─────────────────────────────┘
       │
       │ TextContent + ImageContent
       ▼
  AI sees text AND images

Data Flow & Privacy

1. Your file stays on your machine. The server runs locally via stdio — no network requests, no uploads, no cloud.
2. Read tools never modify your files. All image processing happens in-memory (BytesIO buffers). Write tools change only the exact file you specify, via atomic saves (temp file + swap) that can never leave a half-written workbook.
3. Optional directory sandbox. Set EXCEL_VISION_MCP_ALLOWED_DIRS (path-separator-separated list) to restrict which directories the server may read or write. Unset = no restriction.
4. Memory is freed automatically. After each request, Python's garbage collector reclaims all buffers.

Image Processing Pipeline

Original image in .xlsx (e.g., 2048×1536px PNG)
  ↓ Extract from ZIP archive / drawing layer
  ↓ Resize to fit max dimensions (default 1024px)
  ↓ Compress (JPEG 80% / PNG optimized)
  ↓ Base64 encode
  → ImageContent returned to AI client (~100-300KB per image)

📋 Supported Formats

Image Types

📊 Performance

Tested on real-world enterprise Excel files (macOS, Apple Silicon):

❓ FAQ

🗺️ Roadmap

• Write support — Create workbooks, update cells, write formulas, insert images (v1.1.0)
• Format-aware reading — Bold, strikethrough, highlights, colors; hidden-content handling (v1.2.0)
• Formula evaluation — Show formulas alongside their calculated values
• CSV/TSV support — Extend to other tabular formats
• Conditional formatting — Extract formatting rules
• Chart extraction — Render charts as images

🤝 Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

git clone https://github.com/VOYAGER-Inc/excel-vision-mcp.git
cd excel-vision-mcp
uv sync
uv run pytest  # Run the test suite

📄 License

MIT — use it however you want.