Excel Vision MCP

What excel-vision-mcp MCP server does

The excel-vision-mcp MCP server exposes local .xlsx and, for some write operations, .xlsm workbooks through MCP tools. It can inspect workbook structure, read cell values, search text across sheets, extract embedded images, and return a combined representation of spreadsheet text and visuals.

Reading preserves context that ordinary cell extraction can lose. Returned cell text may include markers for bold, italic, strikethrough, highlights, font colors, merged cells, and hidden cells referenced by visible formulas. Hidden rows and columns are omitted by default, but callers can request them. Image results include base64-encoded ImageContent and cell-position metadata when available.

The server also provides workbook editing operations. Agents can create workbooks, add sheets, update individual cells, write rectangular row ranges, insert local images, apply formatting, and set or auto-fit column widths. Formula strings beginning with = are written as formulas; their calculated values are not available until the workbook is opened in Excel.

How it works

excel-vision-mcp MCP server uses a dual approach for embedded images. It first maps images to worksheet positions and then scans the .xlsx ZIP archive's media directory as a fallback. The read_full_content tool combines sheet text and extracted images in one response, while extract_images focuses on image retrieval and can target one sheet or the whole workbook.

For large workbooks, reading tools limit rows per request. read_excel_data reads a selected row range, and read_full_content paginates each sheet according to its configured maximum. search_excel performs a case-insensitive substring search and returns up to 100 matching cells, excluding hidden content unless requested.

Write operations save atomically, so a failed update does not corrupt the original file. File access can be restricted to configured directories through EXCEL_VISION_MCP_ALLOWED_DIRS; without that setting, the process can access Excel files available to the user account.

Setup and configuration

The package requires Python 3.11 or newer and can run directly with uvx excel-vision-mcp, or be installed with pip and started using the excel-vision-mcp executable. The repository also documents running from source with uv, and a Docker mode that communicates over stdin/stdout and mounts a spreadsheet directory.

MCP configuration examples are provided for Claude Desktop, Cursor, and Windsurf. Add the server as a local stdio process, then restart the client after changing its configuration. When using Docker, the mounted directory is referenced from inside the container, and the documented image configuration limits access to /data.

Tools and capabilities

The tools cover these workflows:

• Inspect sheet names, dimensions, ranges, merged-cell counts, and image totals.
• Read paginated cell data with coordinates and formatting indicators.
• Extract images from one sheet or all sheets with configurable size limits.
• Retrieve a workbook's text and images together with read_full_content.
• Search cell text across a workbook or within a selected sheet.
• Create workbooks and add empty sheets at chosen positions.
• Update individual cells or write rectangular data blocks.
• Insert local PNG, JPEG, GIF, or BMP files at cell anchors.
• Apply fonts, colors, fills, borders, alignment, wrapping, and number formats.
• Set explicit column widths or auto-fit columns with a width cap.

Limitations and notes

The server operates on local file paths rather than a hosted workbook service. Callers must provide absolute paths, and Docker users must use paths inside the mounted container directory. The default row limits and the 100-result search limit may require multiple calls or narrower queries for large files.

Newly written formulas do not have calculated results until Excel opens the file. Image extraction can resize images using maximum width and height settings. Hidden rows and columns are intentionally skipped unless include_hidden is enabled, although hidden cells needed by visible formulas are retained and marked. The documented license is MIT.