Excel Search MCP

🚀 Excel Search MCP

このプロジェクトは、ローカルPC上のExcelファイルを検索および読み取るためのModel Context Protocol (MCP)サーバーを提供します。AIモデルが標準化されたインターフェースを通じてExcelファイルを直接検索および分析できるようになります。

한국어 문서 | 英語ドキュメント

🚀 クイックスタート

このプロジェクトは、AIモデルがローカルPC上のExcelファイルを検索および読み取るためのModel Context Protocol (MCP)サーバーを提供します。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サーバーコア (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 (Model Context Protocol)
• Excel処理：openpyxl、pandas
• ファイルシステム：pathlib、os
• データ変換：json
• ロギング：logging
• テスト：pytest

📦 インストール

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"]
    }
  }
}

📊 利用可能なツール

1. list_excel_files

指定されたディレクトリ内のExcelファイルのリストを返します。 パラメータ：なし（設定ファイルのwork_directoryを使用） 戻り値：

{
  "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ファイル形式とデータ構造をテストするために使用できます。

💻 使用例

基本的な使用法

1. Excelファイルの一覧表示：

   list_excel_filesツールを使用して、作業ディレクトリ内のすべてのExcelファイルを検索します。
   

2. 特定のファイルデータの読み取り：

   read_excel_dataツールを使用して、特定のExcelファイルの内容をJSONに変換します。
   

3. ファイル内のテキスト検索：

   search_in_excelツールを使用して、Excelファイル内で特定のテキストを検索します。
   

高度な使用法

• 大きなファイルの処理：max_rowsパラメータを使用して、メモリ使用量を制限します。
• 特定のワークシートへのアクセス：worksheet_nameパラメータを使用して、目的のワークシートのみを読み取ります。
• 大文字小文字を区別する検索：case_sensitiveパラメータを使用して、正確な検索を行います。

🔒 セキュリティに関する考慮事項

• 作業ディレクトリの制限：構成された作業ディレクトリ外のファイルへのアクセスをブロックします。
• ファイルサイズの制限：大きなファイルによるメモリ枯渇を防止します。
• パーミッションの検証：ファイルアクセス権限を検証し、セキュリティを強化します。
• パストラバーサルの防止：相対パス攻撃から保護します。

🧪 テスト

# 単体テストの実行
pytest tests/test_simple.py

# サーバーテストの実行
pytest tests/test_server.py

# すべてのテストの実行
pytest tests/

📈 パフォーマンス特性

• ファイル検索：1000個のファイルに対して5秒以内
• Excel読み取り：10MBのファイルに対して3秒以内
• メモリ使用量：通常100MB未満
• サポートされる形式：.xlsx、.xls、.xlsm、.xlsb

🤝 コントリビューション

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ライセンスの下でライセンスされています。

📞 サポート

問題が発生した場合や質問がある場合は、イシューを作成してください。