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.
Excel MCP with image extraction and write support — AI agents see and edit xlsx files
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
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
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.
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):
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.
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.
Your file stays on your machine. The server runs locally via stdio — no network requests, no uploads, no cloud.
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.
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.
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
Format
Status
Notes
.xlsx
✅ Fully supported
Excel 2007+ Open XML
.xlsm
✅ Fully supported
Macro-enabled workbooks
.xls
❌ Not supported
Legacy Excel 97-2003 format
.csv
❌ Not supported
Use a CSV-specific tool
Image Types
Image Type
Cell-Mapped
Archive Extraction
PNG
✅
✅
JPEG
✅
✅
GIF
✅
✅
BMP
✅
✅
TIFF
⚠️ Partial
✅
EMF/WMF
❌
✅
=IMAGE() formula
❌
❌
Images in comments
❌
❌
📊 Performance
Tested on real-world enterprise Excel files (macOS, Apple Silicon):
File
Size
Sheets
Images Extracted
Time
Requirements Doc A
4.5 MB
12
24
2.4s
Requirements Doc B
5.0 MB
6
18
2.4s
Requirements Doc C
10.7 MB
6
13
1.5s
Master Spec
16.0 MB
12
40
4.4s
❓ 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 and no files are uploaded anywhere. Read tools never modify your files; write tools change only the file you explicitly target, using atomic saves so a failed write can't corrupt it. You can also sandbox the server to specific directories with the EXCEL_VISION_MCP_ALLOWED_DIRS environment variable.
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.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich Excel Vision?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt Excel Vision einen API-Schlüssel?
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Welchen Transport verwendet Excel Vision?
Excel Vision läuft lokal über stdio.
Wann wurde Excel Vision zuletzt geprüft?
Zuletzt geprüft: 2026-11-09. Excel MCP with image extraction and write support — AI agents see and edit xlsx files