{
  "markdown": "<div align=\"center\">\n\n# 📊 Excel Vision MCP\n\n### Your AI reads the spreadsheet. It can't see the diagram in cell B12.\n\n**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.\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)\n[![PyPI](https://img.shields.io/pypi/v/excel-vision-mcp)](https://pypi.org/project/excel-vision-mcp/)\n\n[Installation](#-quick-start) · [Tools](#-available-tools) · [Configuration](#-configuration) · [How It Works](#-how-it-works) · [FAQ](#-faq)\n\n</div>\n\n---\n\n## 🤔 The Problem\n\nAsk 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.\n\nThe same blind spot applies to the *other* signals authors leave behind:\n\n| What the author did | What other MCP servers report | What Excel Vision MCP reports |\n|---|---|---|\n| Pasted a flowchart in `B12` | *nothing* | The image itself, mapped to `B12` |\n| Struck through a cancelled row | `Legacy export` | `Legacy export [S]` — strikethrough |\n| Highlighted a row for review | `Pending` | `Pending [HL:yellow]` |\n| Hid an internal-cost column | The hidden values, as if normal | Skipped — unless a formula needs it |\n\nSame file. One agent sees a table of strings; the other sees what the author actually meant.\n\n## ✨ Key Features\n\n| Feature | Description |\n|---------|-------------|\n| 🖼️ **Image Extraction** | Extracts all embedded images with cell-position mapping |\n| 📄 **Full Content Reading** | Text + images in a single call — nothing is missed |\n| 🏷️ **Format-Aware Reading** | Reports bold, strikethrough, highlights and font colors so agents read intent, not just text |\n| 🙈 **Hidden-Content Aware** | Skips hidden rows/columns by default, keeping those formulas depend on |\n| ✍️ **Write Support** | Create workbooks, update cells, write formulas, insert images |\n| 🎨 **Formatting** | Colors, fonts, borders, alignment, number formats, auto-fit columns |\n| 🛡️ **Atomic Saves** | A failed write can never corrupt your original file |\n| 📊 **Smart Pagination** | Handles massive spreadsheets without blowing up context |\n| 🔍 **Text Search** | Find content across all sheets instantly |\n| 🔒 **100% Local** | Your files never leave your machine |\n| ⚡ **Fast** | 16MB file with 40 images processed in ~4 seconds |\n| 🖥️ **Cross-Platform** | macOS, Linux, Windows |\n\n### Image Extraction — What Makes This Different\n\nMost Excel MCP servers only read cell values. This server uses a **dual extraction strategy**:\n\n1. **Cell-Position Mapping** (primary) — Maps each image to its exact cell location using `openpyxl-image-loader`\n2. **Archive Scanning** (fallback) — Scans the xlsx ZIP archive's `xl/media/` directory to catch any images missed by method 1\n\nThe result: **zero images left behind**, with position metadata when available.\n\n---\n\n## 👀 See It In Action\n\nA requirements spec where the workflow lives in a pasted diagram and the status lives in cell colors:\n\n> **You:** Review this spec and tell me which features are still in scope, and how the dispatch flow works.\n\n`read_full_content` returns the sheet as text with formatting markers, then the embedded diagram as an image:\n\n```\nRow 1: A1: Feature [B] [HL:blue] | B1: Status [B] [HL:blue]\nRow 2: A2: Vehicle dispatch  | B2: Approved [HL:green]\nRow 3: A3: Legacy CSV export [S] | B3: Cancelled [S]\nRow 4: A4: Driver roll call  | B4: Needs review [HL:yellow]\n\nℹ️ Skipped 3 hidden row(s) with content. Pass include_hidden=true to read them.\n\n**[Image 1]** Sheet: `Spec` | Cell: `B12` | Original: 1180×840px\n[the actual flowchart, as ImageContent]\n```\n\nThe 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.\"*\n\nWithout image support, the second half is unanswerable. Without formatting, the cancelled row looks identical to the active ones.\n\n---\n\n## 🚀 Quick Start\n\n### Install via `uvx` (Recommended)\n\nNo installation needed — runs directly:\n\n```bash\nuvx excel-vision-mcp\n```\n\n### Install via `pip`\n\n```bash\npip install excel-vision-mcp\n```\n\nThen run:\n\n```bash\nexcel-vision-mcp\n```\n\n### Install from source\n\n```bash\ngit clone https://github.com/VOYAGER-Inc/excel-vision-mcp.git\ncd excel-vision-mcp\nuv sync\nuv run excel-vision-mcp\n```\n\n### Run with Docker\n\n```bash\ndocker build -t excel-vision-mcp .\ndocker run --rm -i -v /path/to/spreadsheets:/data excel-vision-mcp\n```\n\nThe 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.\n\nAs an MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"excel-reader\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\", \"-v\", \"/path/to/spreadsheets:/data\", \"excel-vision-mcp\"]\n    }\n  }\n}\n```\n\n---\n\n## 🔧 Configuration\n\nAdd the server to your MCP client's configuration file.\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"excel-reader\": {\n      \"command\": \"uvx\",\n      \"args\": [\"excel-vision-mcp\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nEdit `.cursor/mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"excel-reader\": {\n      \"command\": \"uvx\",\n      \"args\": [\"excel-vision-mcp\"]\n    }\n  }\n}\n```\n\n### Windsurf / VS Code (Copilot)\n\nEdit your MCP settings file:\n\n```json\n{\n  \"mcpServers\": {\n    \"excel-reader\": {\n      \"command\": \"uvx\",\n      \"args\": [\"excel-vision-mcp\"]\n    }\n  }\n}\n```\n\n### Antigravity IDE\n\nEdit `~/.gemini/config/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"excel-reader\": {\n      \"command\": \"uvx\",\n      \"args\": [\"excel-vision-mcp\"]\n    }\n  }\n}\n```\n\n> **Note:** After editing the config, restart your IDE/client to load the new server.\n\n### Restricting file access (optional)\n\nBy 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):\n\n```json\n{\n  \"mcpServers\": {\n    \"excel-reader\": {\n      \"command\": \"uvx\",\n      \"args\": [\"excel-vision-mcp\"],\n      \"env\": {\n        \"EXCEL_VISION_MCP_ALLOWED_DIRS\": \"/Users/me/Documents/spreadsheets:/Users/me/Projects/data\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 🛠️ Available Tools\n\n### `list_sheets`\n\nList all sheets with dimensions, merged cell counts, and image totals. Use this first to understand a workbook's structure.\n\n```\nlist_sheets(file_path=\"/path/to/file.xlsx\")\n```\n\n**Returns:** Sheet names, row×column dimensions, data ranges, merged cell counts, total image count.\n\n---\n\n### `read_excel_data`\n\nRead cell data from a specific sheet with pagination support.\n\n```\nread_excel_data(\n    file_path=\"/path/to/file.xlsx\",\n    sheet_name=\"Sheet1\",      # optional, defaults to first sheet\n    start_row=1,              # optional, 1-indexed\n    max_rows=200,             # optional, default 200\n    include_hidden=False      # optional, read hidden rows/columns too\n)\n```\n\n**Returns:** Cell values organized by row with coordinate labels and markers for merged cells and formatting.\n\n```\nRow 1: A1: Feature [B] [HL:blue] | B1: Status [B] [HL:blue]\nRow 3: A3: Legacy export [S] | B3: Cancelled [S]\nRow 4: A4: Report | B4: Needs review [HL:yellow] | C4: Urgent [B] [C:red]\n```\n\n| Marker | Meaning |\n|--------|---------|\n| `[M]` | Merged cell |\n| `[B]` `[I]` `[S]` | Bold · Italic · Strikethrough |\n| `[HL:color]` | Highlighted background (color named, e.g. `yellow`, `red`) |\n| `[C:color]` | Font color |\n| `[HIDDEN-REF]` | Hidden cell kept because a visible formula references it |\n\nMarkers and a short legend appear only on sheets that actually use formatting, so plain sheets cost no extra context.\n\n---\n\n### `extract_images`\n\nExtract all embedded images from the workbook as base64 `ImageContent`.\n\n```\nextract_images(\n    file_path=\"/path/to/file.xlsx\",\n    sheet_name=\"Overview\",    # optional, None = all sheets\n    max_width=1024,           # optional, resize limit\n    max_height=1024           # optional, resize limit\n)\n```\n\n**Returns:** List of `ImageContent` (base64) with metadata — cell position, sheet name, original dimensions.\n\n---\n\n### `read_full_content` ⭐\n\n**The star tool.** Reads ALL text data AND all embedded images in a single call. Ideal for comprehensive document analysis.\n\n```\nread_full_content(\n    file_path=\"/path/to/file.xlsx\",\n    max_rows_per_sheet=500,   # optional\n    max_image_width=1024,     # optional\n    max_image_height=1024     # optional\n)\n```\n\n**Returns:** Complete workbook contents — every sheet's data as structured text (with formatting markers), followed by every embedded image with cell-position mapping.\n\n**Example use case:** _\"Analyze this requirements document and summarize all use cases, including the workflow diagrams.\"_\n\n---\n\n### Hidden rows & columns\n\nAll read tools **skip hidden rows and columns by default** — an author who hid them signalled they aren't part of the content to review.\n\n**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:\n\n```\nℹ️ Skipped 2 hidden row(s) with content. 1 hidden cell(s) are shown anyway\n   because visible formulas reference them. Pass include_hidden=true to read them.\n```\n\nPass `include_hidden=true` to `read_excel_data`, `read_full_content`, or `search_excel` to read everything.\n\n---\n\n### `get_workbook_overview`\n\nQuick structural summary of a workbook — file size, sheet list, dimensions, image count.\n\n```\nget_workbook_overview(file_path=\"/path/to/file.xlsx\")\n```\n\n---\n\n### `search_excel`\n\nCase-insensitive text search across all cells in the workbook.\n\n```\nsearch_excel(\n    file_path=\"/path/to/file.xlsx\",\n    query=\"revenue\",\n    sheet_name=\"Q4 Report\"    # optional, None = all sheets\n)\n```\n\n**Returns:** Matching cells with sheet name, coordinate, and value. Limited to 100 results.\n\n---\n\n### `create_excel_file`\n\nCreate a new empty workbook with the sheets you name.\n\n```\ncreate_excel_file(\n    file_path=\"/path/to/new.xlsx\",\n    sheet_names=[\"Summary\", \"Detail\"],  # optional, default [\"Sheet1\"]\n    overwrite=False                     # optional, refuses to replace by default\n)\n```\n\n---\n\n### `add_excel_sheet`\n\nAdd a new empty sheet to an existing workbook.\n\n```\nadd_excel_sheet(file_path=\"/path/to/file.xlsx\", sheet_name=\"Q3\", position=0)\n```\n\n---\n\n### `update_excel_cells`\n\nSet individual cells by coordinate. Values starting with `=` are written as formulas.\n\n```\nupdate_excel_cells(\n    file_path=\"/path/to/file.xlsx\",\n    updates={\"A1\": \"Title\", \"B2\": 42, \"C2\": \"=SUM(B2:B10)\"},\n    sheet_name=\"Data\"             # optional, defaults to first sheet\n)\n```\n\n> Note: newly written formulas show no calculated value until the file is opened in Excel. For merged ranges, write to the top-left anchor cell.\n\n---\n\n### `write_excel_rows`\n\nWrite a rectangular block of tabular data in one call.\n\n```\nwrite_excel_rows(\n    file_path=\"/path/to/file.xlsx\",\n    rows=[[\"Item\", \"Qty\"], [\"Widget\", 4], [\"Gadget\", 7]],\n    sheet_name=\"Data\",            # optional\n    start_cell=\"A1\"               # optional\n)\n```\n\n---\n\n### `insert_excel_image`\n\nInsert a local image file into a workbook, anchored at a cell.\n\n```\ninsert_excel_image(\n    file_path=\"/path/to/file.xlsx\",\n    image_path=\"/path/to/chart.png\",\n    cell=\"B2\",\n    sheet_name=\"Report\",          # optional\n    width=480, height=320         # optional display size in px\n)\n```\n\n### `format_excel_cells`\n\nStyle a range: font, colors, borders, alignment, number formats. Only the attributes you pass are changed — existing styling is preserved.\n\n```\nformat_excel_cells(\n    file_path=\"/path/to/file.xlsx\",\n    cell_range=\"A1:D1\",\n    bold=True,\n    font_color=\"FFFFFF\",\n    fill_color=\"4472C4\",\n    horizontal_align=\"center\",\n    border_style=\"thin\",          # thin | medium | thick | double | dashed | dotted\n    border_edges=\"all\",           # \"all\" or \"outline\" (outer edge of range only)\n    number_format=\"#,##0.00\"      # any Excel format code\n)\n```\n\n---\n\n### `set_excel_column_widths`\n\nSet column widths manually and/or auto-fit to content.\n\n```\nset_excel_column_widths(\n    file_path=\"/path/to/file.xlsx\",\n    widths={\"A\": 12, \"B\": 35},    # explicit widths (skipped by auto-fit)\n    auto_fit=True,                # size remaining columns to content\n    max_width=60,                 # cap for auto-fit\n    wrap_overflow=True            # wrap cells longer than the cap\n)\n```\n\n> 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.\n\n---\n\n> 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.\n\n---\n\n## ⚙️ How It Works\n\n### Architecture\n\n```\nYour AI Client (Claude, Cursor, etc.)\n       │\n       │ stdio (JSON-RPC)\n       ▼\n┌─────────────────────────────┐\n│     Excel Vision MCP        │\n│                             │\n│  ┌───────────────────────┐  │\n│  │   openpyxl            │  │──→ Cell data, formulas, merged cells\n│  │   (Excel parser)      │  │\n│  └───────────────────────┘  │\n│                             │\n│  ┌───────────────────────┐  │\n│  │ openpyxl-image-loader │  │──→ Images with cell positions\n│  │ + zipfile (fallback)  │  │\n│  └───────────────────────┘  │\n│                             │\n│  ┌───────────────────────┐  │\n│  │   Pillow              │  │──→ Resize, optimize, base64 encode\n│  │   (image processing)  │  │\n│  └───────────────────────┘  │\n└─────────────────────────────┘\n       │\n       │ TextContent + ImageContent\n       ▼\n  AI sees text AND images\n```\n\n### Data Flow & Privacy\n\n1. **Your file stays on your machine.** The server runs locally via `stdio` — no network requests, no uploads, no cloud.\n2. **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.\n3. **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.\n4. **Memory is freed automatically.** After each request, Python's garbage collector reclaims all buffers.\n\n### Image Processing Pipeline\n\n```\nOriginal image in .xlsx (e.g., 2048×1536px PNG)\n  ↓ Extract from ZIP archive / drawing layer\n  ↓ Resize to fit max dimensions (default 1024px)\n  ↓ Compress (JPEG 80% / PNG optimized)\n  ↓ Base64 encode\n  → ImageContent returned to AI client (~100-300KB per image)\n```\n\n---\n\n## 📋 Supported Formats\n\n| Format | Status | Notes |\n|--------|--------|-------|\n| `.xlsx` | ✅ Fully supported | Excel 2007+ Open XML |\n| `.xlsm` | ✅ Fully supported | Macro-enabled workbooks |\n| `.xls` | ❌ Not supported | Legacy Excel 97-2003 format |\n| `.csv` | ❌ Not supported | Use a CSV-specific tool |\n\n### Image Types\n\n| Image Type | Cell-Mapped | Archive Extraction |\n|------------|:-----------:|:------------------:|\n| PNG | ✅ | ✅ |\n| JPEG | ✅ | ✅ |\n| GIF | ✅ | ✅ |\n| BMP | ✅ | ✅ |\n| TIFF | ⚠️ Partial | ✅ |\n| EMF/WMF | ❌ | ✅ |\n| `=IMAGE()` formula | ❌ | ❌ |\n| Images in comments | ❌ | ❌ |\n\n---\n\n## 📊 Performance\n\nTested on real-world enterprise Excel files (macOS, Apple Silicon):\n\n| File | Size | Sheets | Images Extracted | Time |\n|------|------|--------|:----------------:|-----:|\n| Requirements Doc A | 4.5 MB | 12 | 24 | 2.4s |\n| Requirements Doc B | 5.0 MB | 6 | 18 | 2.4s |\n| Requirements Doc C | 10.7 MB | 6 | 13 | 1.5s |\n| Master Spec | 16.0 MB | 12 | 40 | 4.4s |\n\n---\n\n## ❓ FAQ\n\n<details>\n<summary><b>Why can't it extract images from .xls files?</b></summary>\n\n`.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.\n</details>\n\n<details>\n<summary><b>Why are some images marked as \"orphan\"?</b></summary>\n\nThe 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.\n</details>\n\n<details>\n<summary><b>Can I use this with models that don't support vision?</b></summary>\n\nYes! 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.\n</details>\n\n<details>\n<summary><b>Is my data safe?</b></summary>\n\nYes. 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.\n</details>\n\n<details>\n<summary><b>How do I handle very large files (100MB+)?</b></summary>\n\nThe 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.\n</details>\n\n---\n\n## 🗺️ Roadmap\n\n- [x] **Write support** — Create workbooks, update cells, write formulas, insert images _(v1.1.0)_\n- [x] **Format-aware reading** — Bold, strikethrough, highlights, colors; hidden-content handling _(v1.2.0)_\n- [ ] **Formula evaluation** — Show formulas alongside their calculated values\n- [ ] **CSV/TSV support** — Extend to other tabular formats\n- [ ] **Conditional formatting** — Extract formatting rules\n- [ ] **Chart extraction** — Render charts as images\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please open an issue first to discuss what you'd like to change.\n\n```bash\ngit clone https://github.com/VOYAGER-Inc/excel-vision-mcp.git\ncd excel-vision-mcp\nuv sync\nuv run pytest  # Run the test suite\n```\n\n## 📄 License\n\n[MIT](LICENSE) — use it however you want.\n\n<!-- mcp-name: io.github.VOYAGER-Inc/excel-vision-mcp -->\n\n---\n\n<div align=\"center\">\n\n**Built for AI agents that need to see the whole picture, not just the text.**\n\n⭐ Star this repo if it helped you!\n\n</div>\n",
  "bytes": 19749,
  "sha": "06dab3025125e486735bef31a260f4acbc79968f8790b11e49386fdbf42d0f0b",
  "repo_slug": "voyager-inc/excel-vision-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_voyager_inc_excel_vision_mcp_5c72efc4/readme"
}