Excel Search MCP

🚀 Excel Search MCP

This project provides a Model Context Protocol (MCP) server that enables AI models to search and read Excel files from your local PC. It offers a standardized interface for AI clients supporting MCP to directly search and analyze Excel files.

Korean Documentation | English Documentation

🚀 Quick Start

This project provides a Model Context Protocol (MCP) server that enables AI models to search and read Excel files from your local PC. It allows AI clients supporting MCP (such as Claude Desktop, Cursor) to directly search and analyze Excel files through a standardized interface.

✨ Features

• Excel File Search: Recursively search for Excel files in specified directories
• File Metadata: Provide comprehensive metadata including file paths, sizes, modification dates
• Data Extraction: Convert Excel file contents to JSON format for AI consumption
• Text Search: Search for specific text within Excel files
• Multi-worksheet Support: Handle multiple worksheets and individual worksheet access
• Security Controls: Restrict file access through work directory limitations

🔧 Technical Details

🏗️ Architecture

System Diagram

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

Core Components

1. MCP Server Core (src/server.py)

   • MCP protocol implementation
   • Client communication management
   • Request/response handling

2. Excel Processor (src/excel_processor.py)

   • Excel file reading/parsing
   • Worksheet data extraction
   • JSON conversion logic

3. File Scanner (src/file_scanner.py)

   • Recursive directory scanning
   • Excel file filtering
   • File metadata collection

4. Config Manager (src/config_manager.py)

   • Configuration file management
   • Security policy enforcement
   • Work directory restrictions

🛠️ Technology Stack

• 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

📁 Project Structure

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

📦 Installation

1. Install Dependencies

pip install -r requirements.txt

2. Configure Settings

Create a config.json file to set your work directory:

{
  "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 Client Configuration

Claude Desktop Configuration (claude_desktop_config.json)

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

Cursor Configuration (cursor_mcp_config.json)

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

💻 Usage Examples

Basic Usage

# Use the list_excel_files tool to find all Excel files in the work directory.
Use the list_excel_files tool to find all Excel files in the work directory.

# Use the read_excel_data tool to convert specific Excel file contents to JSON.
Use the read_excel_data tool to convert specific Excel file contents to JSON.

# Use the search_in_excel tool to search for specific text within Excel files.
Use the search_in_excel tool to search for specific text within Excel files.

Advanced Usage

# Use the `max_rows` parameter to limit memory usage
Use the `max_rows` parameter to limit memory usage

# Use the `worksheet_name` parameter to read only desired worksheets
Use the `worksheet_name` parameter to read only desired worksheets

# Use the `case_sensitive` parameter for precise searching
Use the `case_sensitive` parameter for precise searching

📚 Documentation

📊 Available Tools

1. list_excel_files

Returns a list of Excel files in the specified directory. Parameters: None (uses work_directory from config file) Return Value:

{
  "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

Reads Excel file data and converts it to JSON format. Parameters:

• file_path (required): Absolute path to the Excel file
• worksheet_name (optional): Name of worksheet to read (default: first worksheet)
• max_rows (optional): Maximum number of rows to read (default: all rows) Return Value:

{
  "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

Searches for specific text within Excel files. Parameters:

• file_path (required): Absolute path to the Excel file
• search_term (required): Text to search for
• worksheet_name (optional): Specific worksheet to search
• case_sensitive (optional): Whether search should be case sensitive (default: false) Return Value:

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

📁 Sample Data

The project includes various types of Excel file samples from U.S Data.gov - https://catalog.data.gov/dataset/?q=excel

Agricultural Data

• Fruit Data: Apples-2022.xlsx, Avocados-2022.xlsx, Grapes-2022.xlsx, etc.
• Vegetable Data: Carrots-2020.xlsx, Tomatoes-2020.xlsx, Broccoli-2020.xlsx, etc.
• Grain Data: Black_beans-2020.xlsx, Corn_sweet-2020.xlsx, etc.

Government/Public Data

• Education Data: SCH-0009-Limited-English-Proficient-Students-by-state.xlsx
• Agricultural Statistics: BiotechCropsAllTables2024.xlsx
• Trade Data: FoodImports.xlsx, hts_2025_revision_22_xls.xlsx

Scientific/Research Data

• Bird Monitoring: NCRN LAND Bird Monitoring Data 2007 - 2017_Public.xlsx
• Agricultural Production: monsumtable.xlsx, vegtot.xlsx

Legacy Files

• Legacy Excel Files: ELGL 2010 SH 042417.xls, FRVI 2010 SH 042417.xls

These sample datasets can be used to test various Excel file formats and data structures.

🔒 Security Considerations

• Work Directory Restrictions: Blocks access to files outside the configured work directory
• File Size Limits: Prevents memory exhaustion from large files
• Permission Validation: Verifies file access permissions for enhanced security
• Path Traversal Prevention: Protects against relative path attacks

🧪 Testing

# Run unit tests
pytest tests/test_simple.py

# Run server tests
pytest tests/test_server.py

# Run all tests
pytest tests/

📈 Performance Characteristics

• File Search: Under 5 seconds for 1000 files
• Excel Reading: Under 3 seconds for 10MB files
• Memory Usage: Typically under 100MB
• Supported Formats: .xlsx, .xls, .xlsm, .xlsb

🤝 Contributing

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

📄 License

This project is licensed under the MIT License.

📞 Support

If you encounter any issues or have questions, please create an issue.