VOYAGER-Inc/excel-vision-mcp

Your AI reads the spreadsheet. It can't see the diagram in cell B12.
**This fixes that.** Other Excel MCP servers return cell values and silently drop every embedded image, so the flowchart your spec depends on never reaches the model. Excel Vision MCP returns them as native ImageContent your AI can actually look at — alongside the text, formatting, and formulas.
Installation · Tools · Configuration · How It Works · FAQ
---
🤔 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:
| What the author did | What other MCP servers report | What Excel Vision MCP reports |
|---|---|---|
| Pasted a flowchart in B12 | *nothing* | The image itself, mapped to B12 |
| Struck through a cancelled row | Legacy export | Legacy export [S] — strikethrough |
| Highlighted a row for review | Pending | Pending [HL:yellow] |
| Hid an internal-cost column | The hidden values, as if normal | Skipped — unless a formula needs it |
Same file. One agent sees a table of strings; the other sees what the author actually meant.
✨ 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 |
| 🏷️ **Format-Aware Reading** | Reports bold, strikethrough, highlights and font colors so agents read intent, not just text |
| 🙈 **Hidden-Content Aware** | Skips hidden rows/columns by default, keeping those formulas depend on |
| ✍️ **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.
---
👀 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:
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:
Install via pip
Then run:
Install from source
Run with Docker
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.