Excel Search MCP

A Model Context Protocol (MCP) server for searching and reading Excel files from your local PC

한국어 문서 | English Documentation

📋 Project Overview

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.

🎯 Key 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

🏗️ Architecture

System Diagram

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

🚀 Installation & Setup

1. Install Dependencies

2. Configure Settings

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

3. MCP Client Configuration

Claude Desktop Configuration (claude_desktop_config.json)

Cursor Configuration (cursor_mcp_config.json)

📊 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:

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:

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:

📁 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.

🔧 Usage Examples

Basic Usage

1. List Excel Files:

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

2. Read Specific File Data:

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

3. Search Text in Files:

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

Advanced Usage

• Large File Handling: Use the max_rows parameter to limit memory usage

• Specific Worksheet Access: Use the worksheet_name parameter to read only desired worksheets

• Case-Sensitive Search: Use the case_sensitive parameter for precise searching

🔒 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

📈 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.