Excel Vision MCP is an MCP server for AI agents, designed to solve the problem that traditional Excel MCP servers can only read cell text but ignore embedded images. When requirements documents, flowcharts, or annotated diagrams are pasted into cells, returning only text causes the model to give incomplete or even incorrect answers. This tool lets AI see text, formatting, and images at the same time, thereby understanding the full meaning of the spreadsheet.
Key Capabilities
- Image extraction: A dual strategy is used. The primary method uses openpyxl-image-loader to map each image to its exact cell position; the fallback method scans the xl/media/ directory of the xlsx ZIP archive to capture "orphan" images not found by the primary method. The end result is zero missed images, with position metadata provided when available.
- Format-aware reading: When reading cells, it returns formatting markers such as bold, strikethrough, highlighting, and color, and handles hidden rows and columns. Hidden rows and columns are skipped by default, but if a hidden cell is referenced by a visible formula, it is still returned and marked [HIDDEN-REF]. All content can be read via include_hidden=true.
- Full content reading: The read_full_content tool returns the text data of all worksheets (including formatting markers) and all embedded images (including cell position mapping) in a single call, suitable for comprehensive document analysis.
- Write capabilities: Supports creating new workbooks, adding worksheets, updating cells by coordinates (values starting with = are written as formulas), batch writing rectangular data blocks, inserting local images and anchoring them to cells, setting cell formatting (font, color, borders, alignment, number format), and setting column widths (manually or auto-fit). All writes use atomic saving: write to a temporary file first and then replace, avoiding corruption of the original file if saving fails, and preserving .xlsm macros.
- Search and overview: Supports case-insensitive text search across all cells (returning up to 100 results), as well as obtaining a workbook structure summary (file size, worksheet list, dimensions, image count).
Usage
The server transmits JSON-RPC over stdio and must be run in attached mode (such as Docker's -i). Installation methods include uvx (recommended, run directly without installation), pip, source installation, or Docker. When configuring, the server needs to be added to the MCP client's configuration file, for example Claude Desktop, Cursor, Windsurf, VS Code (Copilot), Antigravity IDE, etc. After editing the configuration, you need to restart the IDE/client.
Optionally, restrict the directories the server can read and write via the environment variable EXCEL_VISION_MCP_ALLOWED_DIRS (separate multiple paths with :, and on Windows with ;) to achieve sandboxing.
Use Cases
- Review requirement specification documents containing screenshots, flowcharts, and annotated diagrams to understand the process or state information conveyed in the images.
- Analyze tables with formatting markers (such as strikethrough indicating cancellation and colors indicating status) to accurately determine which content is still in scope.
- Excel document analysis tasks that require AI to understand both text and images.
- Automatically create or modify Excel files, including inserting images and setting formats.
Limitations
- Only .xlsx and .xlsm formats are supported. .xls is an older binary format (BIFF) and is not supported by the libraries used (openpyxl, openpyxl-image-loader), so it must first be converted to .xlsx.
- Newly written formulas will not show calculated values until the file is opened with Excel.
- For merged ranges, writing must target the top-left anchor cell.
- Known limitations of openpyxl: pivot tables and some complex chart features are not preserved when re-saving.
- The primary method for image extraction may miss images not anchored to standard drawing layers, but the fallback scan can capture them; however, these orphan images have no cell position metadata.
- Text-only models will still receive ImageContent, but they will ignore the image data and will not report an error.
- When processing very large files, it is recommended to use the pagination parameters of read_excel_data (start_row + max_rows) rather than read_full_content to control memory.
Privacy and Data Flow
Files remain on the local machine. The server runs locally via stdio, with no network requests, no uploads, and no cloud. Read tools never modify files, and all image processing is done in memory (BytesIO buffer). Write tools only modify the specified file, using atomic saves to ensure no half-written workbook is left behind. After each request, the Python garbage collector automatically releases the buffer.
