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