内容
<div align="center">
# 📊 Excel 视觉MCP
**首个让AI代理在电子表格中看到图像的MCP服务器。**
读取Excel文件并进行完整的內容提取 — 单元格数据、公式、合并单元格、**以及嵌入式图像** — 所有内容都作为多模态内容返回，您的AI可以真正理解。
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
[](https://pypi.org/project/excel-vision-mcp/)
[安装](#-快速开始) · [工具](#-可用工具) · [配置](#-配置) · [工作原理](#-工作原理) · [常见问题](#-常见问题)
</div>
---
## 🤔 问题
您要求AI助手分析Excel文档。它可以很好地读取文本 — 但**完全忽略了文件中嵌入的图表、截图和图像**。这是因为现有的Excel MCP服务器都忽略了图像。
**Excel MCP服务器解决了这个问题。** 它提取嵌入式图像，优化它们，并将它们作为原生的`ImageContent`返回，可供具有视觉能力的AI模型查看和分析 — 以及所有文本数据。
## ✨ 主要功能
| 功能 | 描述 |
|---------|-------------|
| 🖼️ **图像提取** | 提取所有嵌入式图像并映射单元格位置 |
| 📄 **完整内容读取** | 单次调用获取文本 + 图像 — 不遗漏任何内容 |
| 📊 **智能分页** | 处理大型电子表格而不扩大上下文 |
| 🔍 **文本搜索** | 在所有工作表中即时查找内容 |
| 🔒 **100%本地** | 您的文件永远不会离开您的机器 |
| ⚡ **快速** | 处理包含40张图像的16MB文件，约需4秒 |
| 🖥️ **跨平台** | macOS、Linux、Windows |
### 图像提取 — 使其与众不同的原因
大多数Excel MCP服务器只读取单元格值。该服务器使用**双重提取策略**：
1. **单元格位置映射** （主要） — 使用`openpyxl-image-loader`将每个图像映射到其确切的单元格位置
2. **存档扫描** （备用） — 扫描xlsx ZIP存档的`xl/media/`目录，以捕获方法1可能遗漏的任何图像
结果：**零图像遗漏**，如果有的话，还会提供位置元数据。
---
## 🚀 快速开始
### 通过 `uvx` 安装（推荐）
无需安装 — 直接运行：
```bash
uvx excel-vision-mcp
```
### 通过 `pip` 安装
```bash
pip install excel-vision-mcp
```
然后运行：
```bash
excel-vision-mcp
```
### 从源码安装
```bash
git clone https://github.com/VOYAGER-Inc/excel-vision-mcp.git
cd excel-vision-mcp
uv sync
uv run excel-vision-mcp
```
---
## 🔧 配置
将服务器添加到MCP客户端的配置文件中。
### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或 `%APPDATA%\Claude\claude_desktop_config.json` （Windows）：
```json
{
"mcpServers": {
"excel-reader": {
"command": "uvx",
"args": ["excel-vision-mcp"]
}
}
}
```
### Cursor
编辑项目根目录下的 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"excel-reader": {
"command": "uvx",
"args": ["excel-vision-mcp"]
}
}
}
```
### Windsurf / VS Code (Copilot)
编辑MCP设置文件：
```json
{
"mcpServers": {
"excel-reader": {
"command": "uvx",
"args": ["excel-vision-mcp"]
}
}
}
```
### Antigravity IDE
编辑 `~/.gemini/config/mcp_config.json`：
```json
{
"mcpServers": {
"excel-reader": {
"command": "uvx",
"args": ["excel-vision-mcp"]
}
}
}
```
> **注意：** 编辑完配置后，请重启您的IDE/客户端以加载新的服务器。
---
## 🛠️ 可用工具
### `list_sheets`
列出所有工作表及其尺寸、合并单元格数量和图像总数。首先使用此工具来了解工作簿的结构。
```
list_sheets(file_path="/path/to/file.xlsx")
```
**返回：** 工作表名称、行×列尺寸、数据范围、合并单元格数量、图像总数。
---
### `read_excel_data`
从特定的工作表中读取单元格数据，支持分页。
```
read_excel_data(
file_path="/path/to/file.xlsx",
sheet_name="Sheet1", # 可选，默认为第一个工作表
start_row=1, # 可选，1索引
max_rows=200 # 可选，默认为200
)
```
**返回：** 按行组织并带有坐标标签和合并单元格指示器的单元格值。
---
### `extract_images`
从工作簿中提取所有嵌入式图像作为base64 `ImageContent`。
```
extract_images(
file_path="/path/to/file.xlsx",
sheet_name="Overview", # 可选，None = 所有工作表
max_width=1024, # 可选，调整大小限制
max_height=1024 # 可选，调整大小限制
)
```
**返回：** 带有元数据（单元格位置、工作表名称、原始尺寸）的`ImageContent`（base64）列表。
---
### `read_full_content` ⭐
**明星工具。** 在单个调用中读取所有文本数据和嵌入式图像。适用于综合文档分析。
```
read_full_content(
file_path="/path/to/file.xlsx",
max_rows_per_sheet=500, # 可选
max_image_width=1024, # 可选
max_image_height=1024 # 可选
)
```
**返回：** 完整的工作簿内容 — 每个工作表的数据为结构化文本，随后是每个嵌入式图像及其单元格位置映射。
**示例用例：** _“分析此需求文档并总结所有用例，包括工作流图。”_
---
### `get_workbook_overview`
工作簿的快速结构摘要 — 文件大小、工作表列表、尺寸、图像计数。
```
get_workbook_overview(file_path="/path/to/file.xlsx")
```
---
### `search_excel`
在工作簿的所有单元格中进行不区分大小写的文本搜索。
```
search_excel(
file_path="/path/to/file.xlsx",
query="revenue",
sheet_name="Q4 Report" # 可选，None = 所有工作表
)
```
**返回：** 带有工作表名称、坐标和值的匹配单元格。限制为100个结果。
---
## ⚙️ 工作原理
### 架构
```
您的AI客户端（Claude、Cursor等）
│
│ stdio（JSON-RPC）
▼
┌─────────────────────────────┐
│ Excel MCP服务器 │
│ │
│ ┌───────────────────────┐ │
│ │ openpyxl │ │──→ 单元格数据、公式、合并单元格
│ │ （Excel解析器） │ │
│ └───────────────────────┘ │
│ │
│ ┌───────────────────────┐ │
│ │ openpyxl-image-loader │ │──→ 带有单元格位置的图像
│ │ + zipfile（备用） │ │
│ └───────────────────────┘ │
│ │
│ ┌───────────────────────┐ │
│ │ Pillow │ │──→ 调整大小、优化、base64编码
│ │ （图像处理） │ │
│ └───────────────────────┘ │
└─────────────────────────────┘
│
│ 文本内容 + 图像内容
▼
AI看到文本和图像
```
### 数据流和隐私
1. **您的文件保留在您的机器上。** 服务器通过`stdio`在本地运行 — 无网络请求，无上传，无云。
2. **不会写入磁盘。** 所有图像处理都在内存中完成（`BytesIO`缓冲区）。原始`.xlsx`文件从未被修改。
3. **自动释放内存。** 每次请求后，Python的垃圾收集器都会回收所有缓冲区。
### 图像处理管道
```
.xlsx中的原始图像（例如2048×1536像素PNG）
↓ 从ZIP存档/绘图层中提取
↓ 缩放至最大尺寸（默认1024像素）
↓ 压缩（JPEG 80% / PNG优化）
↓ Base64编码
→ 图像内容返回给AI客户端（约100-300KB每张图像）
```
---
## 📋 支持的格式
| 格式 | 状态 | 备注 |
|--------|--------|-------|
| `.xlsx` | ✅ 完全支持 | Excel 2007+ Open XML |
| `.xlsm` | ✅ 完全支持 | 启用宏的工作簿 |
| `.xls` | ❌ 不支持 | 旧版Excel 97-2003格式 |
| `.csv` | ❌ 不支持 | 使用CSV专用工具 |
### 图像类型
| 图像类型 | 单元格映射 | 存档提取 |
|------------|:-----------:|:------------------:|
| PNG | ✅ | ✅ |
| JPEG | ✅ | ✅ |
| GIF | ✅ | ✅ |
| BMP | ✅ | ✅ |
| TIFF | ⚠️ 部分 | ✅ |
| EMF/WMF | ❌ | ✅ |
| `=IMAGE()`公式 | ❌ | ❌ |
| 评论中的图像 | ❌ | ❌ |
---
## 📊 性能
在真实的企业Excel文件上测试（macOS，Apple Silicon）：
| 文件 | 大小 | 工作表 | 提取图像 | 时间 |
|------|------|--------|:----------------:|-----:|
| 需求文档A | 4.5 MB | 12 | 24 | 2.4s |
| 需求文档B | 5.0 MB | 6 | 18 | 2.4s |
| 需求文档C | 10.7 MB | 6 | 13 | 1.5s |
| 主规格 | 16.0 MB | 12 | 40 | 4.4s |
---
## ❓ 常见问题
<details>
<summary><b>为什么无法从.xls文件中提取图像？</b></summary>
`.xls`是旧二进制格式（Excel 97-2003）。它使用与`.xlsx`（基于ZIP的Open XML）完全不同的内部结构（BIFF）。使用的库（`openpyxl`，`openpyxl-image-loader`）仅支持现代Open XML格式。如果您有`.xls`文件，请先使用Excel或LibreOffice将其转换为`.xlsx`。
</details>
<details>
<summary><b>为什么有些图像标记为“孤立”？</b></summary>
主要提取方法（`openpyxl-image-loader`）将图像映射到特定的单元格，但可能会遗漏未锚定到标准绘图层的图像。备用存档扫描器从`xl/media/`目录捕获这些“孤立”图像 — 您获得每个图像，只是没有孤立图像的位置元数据。
</details>
<details>
<summary><b>我可以将它与不支持视觉的模型一起使用吗？</b></summary>
是的！文本数据提取适用于任何模型。图像提取仍将返回`ImageContent`，但纯文本模型将简单地忽略图像数据。您不会收到错误。
</details>
<details>
<summary><b>我的数据安全吗？</b></summary>
是的。服务器**完全在您的本地机器上**通过`stdio`传输运行。不会通过网络发送任何数据，不会将文件上传到任何地方，也不会在磁盘上创建临时文件。您的Excel文件被原样读取，从未被修改。
</details>
<details>
<summary><b>如何处理非常大的文件（100MB+）？</b></summary>
服务器使用`read_only`模式进行数据迭代，并一次处理一个图像。对于极大的文件，请使用`read_excel_data`进行分页（`start_row` + `max_rows`），而不是`read_full_content`来控制内存使用。
</details>
---
## 🗺️ 路线图
- [ ] **写入支持** — 创建和更新单元格，插入图像
- [ ] **图表提取** — 将图表渲染为图像
- [ ] **公式求值** — 显示计算值和公式
- [ ] **条件格式** — 提取格式规则
- [ ] **CSV/TSV支持** — 扩展到其他表格格式
---
## 🤝 贡献
欢迎贡献！请先打开一个问题来讨论您想更改的内容。
```bash
git clone https://github.com/VOYAGER-Inc/excel-vision-mcp.git
cd excel-vision-mcp
uv sync
uv run pytest # 运行测试套件
```
## 📄 许可证
[MIT](LICENSE) — 随意使用。
<!-- mcp-name: io.github.VOYAGER-Inc/excel-vision-mcp -->
---
<div align="center">
**为需要看到全局而非只是文本的AI代理而构建。**
⭐ 如果它对您有帮助，请给这个仓库点赞！
</div>
