excel-search-mcp

🚀 Excel Search MCP

本项目提供了一个模型上下文协议（MCP）服务器，可让AI模型在本地PC上搜索和读取Excel文件，借助标准化接口，支持MCP的AI客户端（如Claude Desktop、Cursor）能直接对Excel文件进行搜索和分析。

🚀 快速开始

本项目提供了一个模型上下文协议（MCP）服务器，使AI模型能够在本地PC上搜索和读取Excel文件。支持MCP的AI客户端（如Claude Desktop、Cursor）可以通过标准化接口直接搜索和分析Excel文件。

安装与设置

1. 安装依赖

pip install -r requirements.txt

2. 配置设置

创建一个 config.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)

{
  "mcpServers": {
    "excel-search-mcp": {
      "command": "python",
      "args": ["C:/path/to/excel-search-mcp/src/server.py"],
      "env": {}
    }
  }
}

Cursor配置 (cursor_mcp_config.json)

{
  "mcpServers": {
    "excel-search-mcp": {
      "command": "python",
      "args": ["C:/path/to/excel-search-mcp/src/server.py"]
    }
  }
}

✨ 主要特性

• Excel文件搜索：在指定目录中递归搜索Excel文件
• 文件元数据：提供包括文件路径、大小、修改日期等全面的元数据
• 数据提取：将Excel文件内容转换为JSON格式，供AI使用
• 文本搜索：在Excel文件中搜索特定文本
• 多工作表支持：处理多个工作表并支持单个工作表访问
• 安全控制：通过工作目录限制来限制文件访问

🔧 技术细节

架构

系统图

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Client     │◄──►│  MCP Server     │◄──►│  Excel Files    │
│   (Claude, etc) │    │  (Python)       │    │  (.xlsx, .xls)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │  File System    │
                       │  (Directory     │
                       │   Scanning)     │
                       └─────────────────┘

核心组件

1. MCP服务器核心 (src/server.py)

   • MCP协议实现
   • 客户端通信管理
   • 请求/响应处理

2. Excel处理器 (src/excel_processor.py)

   • Excel文件读取/解析
   • 工作表数据提取
   • JSON转换逻辑

3. 文件扫描器 (src/file_scanner.py)

   • 递归目录扫描
   • Excel文件过滤
   • 文件元数据收集

4. 配置管理器 (src/config_manager.py)

   • 配置文件管理
   • 安全策略执行
   • 工作目录限制

技术栈

• 语言：Python 3.8+
• MCP框架：mcp（模型上下文协议）
• Excel处理：openpyxl, pandas
• 文件系统：pathlib, os
• 数据转换：json
• 日志记录：logging
• 测试：pytest

项目结构

excel-search-mcp/
├── src/
│   ├── __init__.py
│   ├── server.py              # MCP服务器主程序
│   ├── excel_processor.py     # Excel文件处理
│   ├── file_scanner.py        # 文件扫描
│   ├── config_manager.py      # 配置管理
│   └── data_formatter.py      # 数据格式化
├── tests/
│   ├── test_server.py
│   └── test_simple.py
├── sample/                    # 示例Excel文件
├── requirements.txt
├── pyproject.toml
├── config.json               # 配置文件
└── README.md

💻 使用示例

基础用法

1. 列出Excel文件：

使用 list_excel_files 工具查找工作目录中的所有Excel文件。

2. 读取特定文件数据：

使用 read_excel_data 工具将特定Excel文件内容转换为JSON。

3. 在文件中搜索文本：

使用 search_in_excel 工具在Excel文件中搜索特定文本。

高级用法

• 大文件处理：使用 max_rows 参数限制内存使用
• 特定工作表访问：使用 worksheet_name 参数仅读取所需的工作表
• 区分大小写搜索：使用 case_sensitive 参数进行精确搜索

📦 可用工具

1. list_excel_files

返回指定目录中的Excel文件列表。 参数：无（使用配置文件中的工作目录） 返回值：

{
  "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格式。 参数：

• file_path（必需）：Excel文件的绝对路径
• worksheet_name（可选）：要读取的工作表名称（默认：第一个工作表）
• max_rows（可选）：要读取的最大行数（默认：所有行） 返回值：

{
  "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文件中搜索特定文本。 参数：

• file_path（必需）：Excel文件的绝对路径
• search_term（必需）：要搜索的文本
• worksheet_name（可选）：要搜索的特定工作表
• case_sensitive（可选）：搜索是否区分大小写（默认：false） 返回值：

{
  "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文件示例，数据来源于美国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

旧版文件

• 旧版Excel文件：ELGL 2010 SH 042417.xls, FRVI 2010 SH 042417.xls

这些示例数据集可用于测试各种Excel文件格式和数据结构。

🔒 安全注意事项

• 工作目录限制：阻止对配置工作目录之外的文件的访问
• 文件大小限制：防止大文件导致内存耗尽
• 权限验证：验证文件访问权限以增强安全性
• 路径遍历防护：防止相对路径攻击

🧪 测试

# 运行单元测试
pytest tests/test_simple.py

# 运行服务器测试
pytest tests/test_server.py

# 运行所有测试
pytest tests/

🤝 贡献代码

1. 分叉仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

本项目采用MIT许可证。

📞 支持

如果遇到任何问题或有疑问，请创建一个issue。

한국어 문서 | English Documentation