excel-vision-mcp

<div align="center">

# 📊 Excel Vision MCP

**The first MCP server that lets AI agents _see_ images inside your spreadsheets.**

Read **and write** Excel files with full content extraction — cell data, formulas, merged cells, **and embedded images** — all returned as multimodal content your AI can actually understand.

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
[![PyPI](https://img.shields.io/pypi/v/excel-vision-mcp)](https://pypi.org/project/excel-vision-mcp/)

[Installation](#-quick-start) · [Tools](#-available-tools) · [Configuration](#-configuration) · [How It Works](#-how-it-works) · [FAQ](#-faq)

</div>

---

## 🤔 The Problem

You ask your AI assistant to analyze an Excel document. It reads the text just fine — but **completely misses the diagrams, screenshots, and charts** embedded in the file. That's because every existing Excel MCP server ignores images.

**Excel MCP Server fixes this.** It extracts embedded images, optimizes them, and returns them as native `ImageContent` that vision-capable AI models can see and analyze — alongside all the text data.

## ✨ Key Features

| Feature | Description |
|---------|-------------|
| 🖼️ **Image Extraction** | Extracts all embedded images with cell-position mapping |
| 📄 **Full Content Reading** | Text + images in a single call — nothing is missed |
| ✍️ **Write Support** | Create workbooks, update cells, write formulas, insert images |
| 🎨 **Formatting** | Colors, fonts, borders, alignment, number formats, auto-fit columns |
| 🛡️ **Atomic Saves** | A failed write can never corrupt your original file |
| 📊 **Smart Pagination** | Handles massive spreadsheets without blowing up context |
| 🔍 **Text Search** | Find content across all sheets instantly |
| 🔒 **100% Local** | Your files never leave your machine |
| ⚡ **Fast** | 16MB file with 40 images processed in ~4 seconds |
| 🖥️ **Cross-Platform** | macOS, Linux, Windows |

### 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.

---

## 🚀 Quick Start

### Install via `uvx` (Recommended)

No installation needed — runs directly:

```bash
uvx excel-vision-mcp
```

### Install via `pip`

```bash
pip install excel-vision-mcp
```

Then run:

```bash
excel-vision-mcp
```

### Install from source

```bash
git clone https://github.com/VOYAGER-Inc/excel-vision-mcp.git
cd excel-vision-mcp
uv sync
uv run 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):

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

### Cursor

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

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

### Windsurf / VS Code (Copilot)

Edit your MCP settings file:

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

### Antigravity IDE

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

```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):

```json
{
  "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
)
```

**Returns:** Cell values organized by row with coordinate labels and merged cell indicators.

---

### `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, 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."_

---

### `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 (Claud