Excel MCP Server enables AI coding assistants to search, read, and analyze Excel spreadsheets stored locally on your computer. It provides intelligent file discovery and data extraction capabilities that transform complex workbook contents into structured formats for AI processing. Key capabilities: - Recursive directory scanning to locate .xlsx and .xls files across your local file system - Full content extraction from individual worksheets with conversion to JSON format - Text search across spreadsheet cells to quickly find specific values and data - Metadata retrieval including file paths, sizes, and modification timestamps - Configurable security controls that restrict access to designated working directories - Multi-worksheet support for accessing specific sheets or entire workbooks

Excel Search MCP

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

[](https://smithery.ai/) [](https://python.org) [](LICENSE) [](https://modelcontextprotocol.io/)

한국어 문서 | 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

🏗️ 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

📁 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 & Setup

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

📊 Available Tools

1. list_excel_files

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

Parameters: