📊 Excel Vision MCP

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

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

Installation · Tools · Configuration · How It Works · FAQ

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

Related MCP server: Excel MCP Server

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

🚀 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

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

🛠️ 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.

⚙️ How It Works

Architecture

Your AI Client (Claude, Cursor, etc.)
       │
       │ stdio (JSON-RPC)
       ▼
┌─────────────────────────────┐
│     Excel MCP Server        │
│                             │
│  ┌───────────────────────┐  │
│  │   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. Nothing is written to disk. All image processing happens in-memory (BytesIO buffers). The original .xlsx file is never modified.

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

.xls is the legacy binary format (Excel 97-2003). It uses a completely different internal structure (BIFF) compared to .xlsx (ZIP-based Open XML). The libraries used (openpyxl, openpyxl-image-loader) only support the modern Open XML format. If you have .xls files, convert them to .xlsx using Excel or LibreOffice first.

The primary extraction method (openpyxl-image-loader) maps images to specific cells but may miss images that aren't anchored to the standard drawing layer. The fallback archive scanner catches these "orphan" images from the xl/media/ directory — you get every image, just without cell-position metadata for orphans.

Yes! Text data extraction works perfectly with any model. Image extraction will still return ImageContent, but text-only models will simply ignore the image data. You won't get errors.

Yes. The server runs entirely on your local machine via stdio transport. No data is sent over the network, no files are uploaded anywhere, and no temporary files are created on disk. Your Excel files are read in-place and never modified.

The server uses read_only mode for data iteration and processes images in-memory one at a time. For extremely large files, use read_excel_data with pagination (start_row + max_rows) instead of read_full_content to control memory usage.

🗺️ Roadmap

• Write support — Create and update cells, insert images

• Chart extraction — Render charts as images

• Formula evaluation — Show calculated values alongside formulas

• Conditional formatting — Extract formatting rules

• CSV/TSV support — Extend to other tabular formats

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

Built for AI agents that need to see the whole picture, not just the text.

⭐ Star this repo if it helped you!