# free-mcp-excel

**Repository Path**: fanzhiyu/free-mcp-excel

## Basic Information

- **Project Name**: free-mcp-excel
- **Description**: 面向 AI 应用的轻量化 Excel 处理 MCP 服务，纯本地运行无网络依赖，支持.xlsx/.xls 多格式兼容、多工作表批量读写、结构化数据规整，一键集成至 Claude/Cursor 等 AI 客户端，大幅降低 AI 处理 Excel 文件的开发成本，提升数据处理效率。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-08
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Excel MCP Server

本地Excel MCP（Model Context Protocol）服务，提供轻量、开箱即用的Excel文件解析能力。

## 特性

- ✅ **纯本地运行**：通过stdio通信，无端口监听、无网络依赖
- ✅ **多格式支持**：自动识别并兼容 `.xlsx` 和 `.xls` 两种格式
- ✅ **灵活部署**：支持uvx自动管理依赖或pip手动安装
- ✅ **标准化协议**：遵循MCP协议规范，兼容Claude Desktop、Cursor等AI客户端
- ✅ **高性能**：直接使用文件路径，无需Base64编码/解码，特别适合大文件处理
- ✅ **健壮性保障**：内置文件校验、格式识别、异常处理等机制

## 快速开始

### 环境要求

- Python 3.8+
- MCP客户端（如Claude Desktop、Cursor等）

### 安装方式

#### 方式一：从PyPI安装（推荐）

**使用 pip 安装（推荐，自动安装所有依赖）**：
```bash
pip install free-mcp-excel
```

这会自动安装所有必需的依赖，包括：
- `mcp>=0.9.0` - MCP SDK
- `openpyxl>=3.0.0` - Excel .xlsx 处理
- `pandas>=1.5.0` - 数据处理（约11.8MB）
- `xlrd>=2.0.0` - Excel .xls 读取
- `xlwt>=1.3.0` - Excel .xls 写入
- `pycel>=1.0b0` - 公式计算引擎

**或使用 uvx（首次安装较慢）**：
```bash
uvx free-mcp-excel
```

**注意**：
- `uvx` 首次安装需要下载约30MB依赖（pandas 11.8MB, numpy 15.6MB, networkx 1.8MB等），可能需要几分钟
- 如果网络较慢或遇到 "No server info found" 错误，建议使用 `pip install` 方式

#### 方式二：从源码安装

```bash
# 克隆项目
git clone https://gitee.com/fanzhiyu/free-mcp-excel.git
cd free-mcp-excel

# 安装依赖（自动安装所有必需库）
pip install -r requirements.txt

# 或使用开发模式安装（推荐）
pip install -e .
```

#### 方式三：手动安装依赖（如果自动安装失败）

如果自动安装遇到问题，可以手动安装依赖：

```bash
# 安装核心依赖
pip install mcp>=0.9.0
pip install openpyxl>=3.0.0
pip install pandas>=1.5.0
pip install xlrd>=2.0.0
pip install xlwt>=1.3.0
pip install pycel>=1.0b0

# 然后安装包
pip install free-mcp-excel
```

或者一次性安装：
```bash
pip install mcp openpyxl pandas xlrd xlwt pycel
pip install free-mcp-excel
```

### 配置MCP客户端

#### Cursor IDE配置

在项目根目录创建或编辑 `.cursor/mcp.json`：

**推荐配置（使用 pip 安装后）**：
```json
{
  "mcpServers": {
    "free-mcp-excel": {
      "command": "python",
      "args": ["-m", "free_mcp_excel"]
    }
  }
}
```

**或使用 uvx（首次安装较慢）**：
```json
{
  "mcpServers": {
    "free-mcp-excel": {
      "command": "uvx",
      "args": ["free-mcp-excel"]
    }
  }
}
```

#### Claude Desktop配置

编辑配置文件（macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`）：

**推荐配置（使用 pip 安装后）**：
```json
{
  "mcpServers": {
    "free-mcp-excel": {
      "command": "python",
      "args": ["-m", "free_mcp_excel"]
    }
  }
}
```

**或使用 uvx（首次安装较慢）**：
```json
{
  "mcpServers": {
    "free-mcp-excel": {
      "command": "uvx",
      "args": ["free-mcp-excel"]
    }
  }
}
```

#### 其他MCP客户端

对于其他支持MCP的客户端，推荐使用以下配置：

**推荐配置（pip 安装后）**：
```json
{
  "mcpServers": {
    "free-mcp-excel": {
      "command": "python",
      "args": ["-m", "free_mcp_excel"]
    }
  }
}
```

**或使用 uvx（首次安装较慢）**：
```json
{
  "mcpServers": {
    "free-mcp-excel": {
      "command": "uvx",
      "args": ["free-mcp-excel"]
    }
  }
}
```

**安装建议**：
- 首次使用建议：`pip install free-mcp-excel`（更快更稳定）
- 如果已安装，两种配置方式都可以使用

**故障排查**：
- 如果遇到 "No server info found" 错误：
  1. 检查是否已正确安装：`pip list | grep free-mcp-excel`
  2. 检查依赖是否完整：`pip list | grep -E "mcp|openpyxl|pandas"`
  3. 如果依赖缺失，手动安装：`pip install -r requirements.txt`
- 如果使用 `uvx` 安装较慢，建议改用 `pip install free-mcp-excel`
- 更多问题请参考 [快速安装指南](docs/快速安装指南.md)

详细配置说明请参考 [使用指南](docs/使用指南.md)。

## 可用工具

### 读取类工具
- **read_sheet_names**：读取所有工作表名称
- **read_sheet_data**：读取工作表数据（支持范围、行列过滤、空行处理）
- **read_cell_data**：读取单个或范围单元格数据
- **read_cell_formula**：读取单元格公式
- **read_merged_cells**：读取合并单元格信息
- **read_chart_info**：读取图表信息
- **read_table_info**：读取表格信息
- **get_workbook_info**：获取工作簿基本信息（格式、工作表列表等）

### 写入类工具
- **create_workbook**：创建新工作簿
- **create_sheet**：创建工作表
- **write_cell_data**：写入单元格数据
- **write_cell_formula**：写入单元格公式
- **write_range_data**：批量写入范围数据
- **merge_cells** / **unmerge_cells**：合并/取消合并单元格
- **create_chart**：创建图表（支持多种图表类型）
- **update_chart** / **delete_chart**：更新/删除图表
- **create_table**：创建表格
- **save_workbook**：保存工作簿

### 计算类工具
- **calc_cell_data**：计算单元格值（支持公式计算）
- **calc_range_data**：批量计算范围数据
- **evaluate_formula**：评估公式表达式

### 工具类工具
- **excel_to_base64** / **base64_to_excel**：文件格式转换（已废弃，不推荐使用）

**特性说明**：
- ✅ 支持 `.xlsx` 和 `.xls` 两种格式
- ✅ 智能处理稀疏数据（大量空行）
- ✅ 自动识别表头（即使首行为空行）
- ✅ 支持合并单元格、公式、图表等高级功能

## Cursor/IDE 提示词（复制即用）

配置完成后，在 Cursor 等 IDE 中可以直接使用以下提示词：

```
你是一个专业的Excel数据分析助手，可以使用Excel MCP服务工具来处理Excel文件。

## 核心工具

### 读取类
- **read_sheet_names**: 获取工作表列表
  - 参数：`file_path`（文件路径，必需）
  
- **read_sheet_data**: 读取工作表数据
  - 参数：`file_path`（必需）、`sheet`（可选）、`range`（可选，如"A1:B10"）、`skip_empty_rows`（可选，默认true）
  - `skip_empty_rows=true`：跳过空行，适合数据分析
  - `skip_empty_rows=false`：保留空行，自动识别第一个非空行作为表头
  
- **read_cell_data**: 读取单元格数据
  - 参数：`file_path`、`sheet`、`cell`（如"A1"或"A1:B10"）

### 写入类
- **create_workbook**: 创建新工作簿
  - 参数：`sheet_name`（可选）
  - 返回：`file`（Base64编码，需先保存为文件，然后使用file_path）
  
- **write_cell_data**: 写入单个单元格
  - 参数：`file_path`、`sheet`、`cell`、`value`、`data_type`（可选）
  
- **write_range_data**: 批量写入
  - 参数：`file_path`、`sheet`、`start_cell`、`data`（二维数组）

### 计算类
- **calc_cell_data**: 计算单元格值
  - 参数：`file_path`、`sheet`、`cell`、`force_recalc`（可选）

## 使用规则

1. **文件参数**：所有工具使用 `file_path`（文件路径），不支持Base64，直接读取文件性能优异
2. **工作流程**：读取→分析→写入→文件直接修改，无需额外保存
3. **空行处理**：数据分析用`skip_empty_rows=true`，保持格式用`false`
4. **错误处理**：检查返回的`status`，错误时读取`error.message`告知用户

## 示例

用户："这个Excel文件有哪些工作表？"
→ 调用 `read_sheet_names`，参数：`{"file_path": "文件路径"}`

用户："读取'销售数据'工作表的所有数据"
→ 调用 `read_sheet_data`，参数：`{"file_path": "文件路径", "sheet": "销售数据", "skip_empty_rows": true}`

用户："创建一个包含员工信息的Excel文件"
→ 调用 `create_workbook` → 保存为临时文件 → `write_range_data`写入数据（使用file_path）→ 文件已保存

现在请帮助用户处理Excel文件，根据用户需求智能选择合适的工具。
```

## 文档

- [📖 使用指南](docs/使用指南.md) - 安装、配置和使用说明
- [📋 完整方案](docs/完整方案.md) - 详细的技术实现方案和架构设计
- [📚 文档索引](docs/README.md) - 所有文档的完整列表

### 快速链接

- **想快速上手？** → [使用指南](docs/使用指南.md)
- **想了解如何调用工具？** → 查看上方的"Cursor/IDE 提示词"部分
- **想深入了解技术细节？** → [完整方案](docs/完整方案.md)

## 官方资源

- [MCP官方文档](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [MCP规范文档](https://mcp.fleeto.us/spec/)
- [MCP中文文档](https://mcp.wiki/introduction)

## 许可证

本项目采用 [MIT License](LICENSE) 许可证。

## 贡献

欢迎提交Issue和Pull Request！