Excel Vision MCP 是一个面向 AI 智能体的 MCP 服务器，旨在解决传统 Excel MCP 服务器只能读取单元格文本、却忽略嵌入图片的问题。当需求文档、流程图或标注图被粘贴到单元格中时，仅返回文本会导致模型给出不完整甚至错误的回答。该工具让 AI 能够同时看到文本、格式和图片，从而理解表格的完整含义。
主要能力
- 图片提取：采用双重策略。主方法使用 openpyxl-image-loader 将每张图片映射到其精确的单元格位置；兜底方法扫描 xlsx ZIP 归档的 xl/media/ 目录，捕获未被主方法发现的“孤儿”图片。最终实现零图片遗漏，并在可用时提供位置元数据。
- 格式感知读取：读取单元格时返回加粗、删除线、高亮、颜色等格式标记，并处理隐藏行列。默认跳过隐藏行列，但若隐藏单元格被可见公式引用，则仍会返回并标记 [HIDDEN-REF]。可通过 include_hidden=true 读取全部内容。
- 完整内容读取：read_full_content 工具在一次调用中返回所有工作表的文本数据（含格式标记）和所有嵌入图片（含单元格位置映射），适合全面文档分析。
- 写入能力：支持创建新工作簿、添加工作表、按坐标更新单元格（以 = 开头的值写为公式）、批量写入矩形数据块、插入本地图片并锚定到单元格、设置单元格格式（字体、颜色、边框、对齐、数字格式）、设置列宽（手动或自动适应）。所有写入均使用原子保存：先写临时文件再替换，避免保存失败损坏原文件，且保留 .xlsm 宏。
- 搜索与概览：支持跨所有单元格的大小写不敏感文本搜索（最多返回 100 条结果），以及获取工作簿结构摘要（文件大小、工作表列表、维度、图片数量）。
使用方式
该服务器通过 stdio 传输 JSON-RPC，需以附加模式运行（如 Docker 的 -i）。安装方式包括 uvx（推荐，无需安装直接运行）、pip、源码安装或 Docker。配置时需将服务器添加到 MCP 客户端的配置文件中，例如 Claude Desktop、Cursor、Windsurf、VS Code (Copilot)、Antigravity IDE 等。编辑配置后需重启 IDE/客户端。
可选地，通过环境变量 EXCEL_VISION_MCP_ALLOWED_DIRS 限制服务器可读写的目录（多个路径用 : 分隔，Windows 用 ;），实现沙箱化。
适用场景
- 审查包含截图、流程图、标注图的需求规格文档，理解图片中传达的流程或状态信息。
- 分析带有格式标记（如删除线表示取消、颜色表示状态）的表格，准确判断哪些内容仍在范围内。
- 需要 AI 同时理解文本和图片的 Excel 文档分析任务。
- 自动化创建或修改 Excel 文件，包括插入图片和设置格式。
限制
- 仅支持 .xlsx 和 .xlsm 格式。.xls 是旧版二进制格式（BIFF），使用的库（openpyxl、openpyxl-image-loader）不支持，需先转换为 .xlsx。
- 新写入的公式在文件用 Excel 打开前不会显示计算值。
- 对于合并区域，写入需定位到左上角锚点单元格。
- openpyxl 的已知限制：重新保存时不会保留数据透视表和某些复杂图表功能。
- 图片提取的主方法可能遗漏未锚定到标准绘图层的图片，但兜底扫描可捕获，只是这些孤儿图片没有单元格位置元数据。
- 纯文本模型仍会收到 ImageContent，但会忽略图片数据，不会报错。
- 处理超大文件时，建议使用 read_excel_data 的分页参数（start_row + max_rows）而非 read_full_content 以控制内存。
隐私与数据流
文件保留在本地机器上。服务器通过 stdio 本地运行，无网络请求、无上传、无云端。读取工具从不修改文件，所有图片处理在内存中完成（BytesIO 缓冲区）。写入工具仅修改指定的文件，通过原子保存确保不会留下半写入的工作簿。每次请求后，Python 垃圾回收器自动释放缓冲区。
