内容
# Excel Search MCP
一个用于从本地PC搜索和读取Excel文件的模型上下文协议 (MCP) 服务器
[](https://smithery.ai/)
[](https://python.org)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[한국어 문서](README_ko.md) | [English Documentation](README.md)
## 📋 项目概述
此项目提供了一个模型上下文协议 (MCP) 服务器，使AI模型能够从您的本地PC搜索和读取Excel文件。它允许支持MCP的AI客户端（如Claude Desktop、Cursor）通过标准化接口直接搜索和分析Excel文件。
## 🎯 主要特性
- **Excel文件搜索**：递归搜索指定目录中的Excel文件
- **文件元数据**：提供全面的元数据，包括文件路径、大小、修改日期
- **数据提取**：将Excel文件内容转换为JSON格式，供AI使用
- **文本搜索**：在Excel文件中搜索特定文本
- **多工作表支持**：处理多个工作表和单个工作表访问
- **安全控制**：通过工作目录限制来限制文件访问
## 🏗️ 架构
### 系统图
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ AI Client │◄──►│ MCP Server │◄──►│ Excel Files │
│ (Claude, etc) │ │ (Python) │ │ (.xlsx, .xls) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ File System │
│ (Directory │
│ Scanning) │
└─────────────────┘
```
### 核心组件
1. **MCP Server Core** (`src/server.py`)
- MCP协议实现
- 客户端通信管理
- 请求/响应处理
2. **Excel Processor** (`src/excel_processor.py`)
- Excel文件读取/解析
- 工作表数据提取
- JSON转换逻辑
3. **File Scanner** (`src/file_scanner.py`)
- 递归目录扫描
- Excel文件过滤
- 文件元数据收集
4. **Config Manager** (`src/config_manager.py`)
- 配置文件管理
- 安全策略执行
- 工作目录限制
## 🛠️ 技术栈
- **Language**: Python 3.8+
- **MCP Framework**: mcp (Model Context Protocol)
- **Excel Processing**: openpyxl, pandas
- **File System**: pathlib, os
- **Data Conversion**: json
- **Logging**: logging
- **Testing**: pytest
## 📁 项目结构
```
excel-search-mcp/
├── src/
│ ├── __init__.py
│ ├── server.py # MCP server main
│ ├── excel_processor.py # Excel file processing
│ ├── file_scanner.py # File scanning
│ ├── config_manager.py # Configuration management
│ └── data_formatter.py # Data formatting
├── tests/
│ ├── test_server.py
│ └── test_simple.py
├── sample/ # Sample Excel files
├── requirements.txt
├── pyproject.toml
├── config.json # Configuration file
└── README.md
```
## 🚀 安装与设置
### 1. 安装依赖
```bash
pip install -r requirements.txt
```
### 2. 配置设置
创建一个 `config.json` 文件来设置您的工作目录：
```json
{
"work_directory": "/path/to/your/excel/files",
"excel": {
"supported_extensions": [".xlsx", ".xls", ".xlsm", ".xlsb"],
"max_file_size_mb": 100,
"max_files_per_search": 1000,
"recursive_search": true
}
}
```
### 3. MCP客户端配置
#### Claude Desktop配置 (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"excel-search-mcp": {
"command": "python",
"args": ["C:/path/to/excel-search-mcp/src/server.py"],
"env": {}
}
}
}
```
#### Cursor配置 (`cursor_mcp_config.json`)
```json
{
"mcpServers": {
"excel-search-mcp": {
"command": "python",
"args": ["C:/path/to/excel-search-mcp/src/server.py"]
}
}
}
```
## 📊 可用工具
### 1. `list_excel_files`
返回指定目录中的Excel文件列表。
**Parameters**: None (使用配置文件中的work_directory)
**Return Value**:
```json
{
"success": true,
"directory": "/path/to/directory",
"total_files": 5,
"scanned_files": 100,
"files": [
{
"file_path": "/path/to/file.xlsx",
"file_name": "file.xlsx",
"file_size": 1024000,
"modified_time": "2024-01-01T12:00:00Z",
"created_time": "2024-01-01T10:00:00Z",
"extension": ".xlsx"
}
],
"supported_extensions": [".xlsx", ".xls", ".xlsm", ".xlsb"]
}
```
### 2. `read_excel_data`
读取Excel文件数据并将其转换为JSON格式。
**Parameters**:
- `file_path` (required): Excel文件的绝对路径
- `worksheet_name` (optional): 要读取的工作表的名称（默认：第一个工作表）
- `max_rows` (optional): 要读取的最大行数（默认：所有行）
**Return Value**:
```json
{
"success": true,
"file_path": "/path/to/file.xlsx",
"worksheet_name": "Sheet1",
"headers": ["Column1", "Column2", "Column3"],
"rows": [
["Value1", "Value2", "Value3"],
["Value4", "Value5", "Value6"]
],
"row_count": 2,
"column_count": 3,
"data_types": {
"Column1": "object",
"Column2": "int64",
"Column3": "float64"
}
}
```
### 3. `search_in_excel`
在Excel文件中搜索特定文本。
**Parameters**:
- `file_path` (required): Excel文件的绝对路径
- `search_term` (required): 要搜索的文本
- `worksheet_name` (optional): 要搜索的特定工作表
- `case_sensitive` (optional): 搜索是否应区分大小写（默认：false）
**Return Value**:
```json
{
"success": true,
"file_path": "/path/to/file.xlsx",
"worksheet_name": "Sheet1",
"search_term": "search term",
"case_sensitive": false,
"total_matches": 3,
"matches": [
{
"row": 1,
"column": "Column1",
"column_index": 0,
"value": "value containing search term",
"cell_address": "A1"
}
]
}
```
## 📁 示例数据
该项目包括各种类型的Excel文件示例：
来自U.S Data.gov - https://catalog.data.gov/dataset/?q=excel
### 农业数据
- **水果数据**: `Apples-2022.xlsx`, `Avocados-2022.xlsx`, `Grapes-2022.xlsx` 等.
- **蔬菜数据**: `Carrots-2020.xlsx`, `Tomatoes-2020.xlsx`, `Broccoli-2020.xlsx` 等.
- **谷物数据**: `Black_beans-2020.xlsx`, `Corn_sweet-2020.xlsx` 等.
### 政府/公共数据
- **教育数据**: `SCH-0009-Limited-English-Proficient-Students-by-state.xlsx`
- **农业统计**: `BiotechCropsAllTables2024.xlsx`
- **贸易数据**: `FoodImports.xlsx`, `hts_2025_revision_22_xls.xlsx`
### 科学/研究数据
- **鸟类监测**: `NCRN LAND Bird Monitoring Data 2007 - 2017_Public.xlsx`
- **农业生产**: `monsumtable.xlsx`, `vegtot.xlsx`
### 遗留文件
- **Legacy Excel Files**: `ELGL 2010 SH 042417.xls`, `FRVI 2010 SH 042417.xls`
这些示例数据集可用于测试各种Excel文件格式和数据结构。
## 🔧 使用示例
### 基本用法
1. **列出Excel文件**:
```
使用 list_excel_files 工具查找工作目录中的所有Excel文件。
```
2. **读取特定文件数据**:
```
使用 read_excel_data 工具将特定Excel文件内容转换为JSON。
```
3. **在文件中搜索文本**:
```
使用 search_in_excel 工具在Excel文件中搜索特定文本。
```
### 高级用法
- **处理大文件**: 使用 `max_rows` 参数限制内存使用
- **访问特定工作表**: 使用 `worksheet_name` 参数仅读取所需的工作表
- **区分大小写搜索**: 使用 `case_sensitive` 参数进行精确搜索
## 🔒 安全注意事项
- **工作目录限制**: 阻止访问配置的工作目录之外的文件
- **文件大小限制**: 防止大文件耗尽内存
- **权限验证**: 验证文件访问权限以增强安全性
- **路径遍历预防**: 防止相对路径攻击
## 🧪 测试
```bash
# Run unit tests
pytest tests/test_simple.py
# Run server tests
pytest tests/test_server.py
# Run all tests
pytest tests/
```
## 📈 性能特点
- **文件搜索**: 1000个文件在5秒内
- **Excel读取**: 10MB文件在3秒内
- **内存使用**: 通常低于100MB
- **支持的格式**: .xlsx, .xls, .xlsm, .xlsb
## 🤝 贡献
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 许可证
本项目根据MIT许可证获得许可。
## 📞 支持
如果您遇到任何问题或有疑问，请创建一个issue。
MCP 市场
