Excel Search

This MCP server lets you search and read Excel files from your local PC, exposing a standardized interface so AI clients can discover files, retrieve metadata, read worksheet data as JSON, and search text across workbooks securely.

How to use

You run the MCP server locally and connect to it from an MCP-enabled AI client such as Claude Desktop or Cursor. Start the server, then configure your client to point at the local MCP endpoint. You can list available Excel files, read worksheet data as JSON, and search for specific text within workbooks. Access is constrained to a designated work directory to protect your files.

Typical workflows include: first listing all Excel files in your work directory, then reading data from a chosen workbook to feed an AI analysis, and finally performing targeted text searches within one or more worksheets. You can specify a worksheet name to focus the data extraction and limit the number of rows to keep memory usage predictable.

How to install

Prerequisites you need before starting the server: a Python 3.8+ environment and access to a shell (Command Prompt, PowerShell, or a Unix shell). Ensure you have WiFi or network access only for local connections, and you have a designated work directory for your Excel files.

Step 1: Install Python dependencies from the project’s requirements file.

pip install -r requirements.txt

Step 2: Create a configuration file named config.json in a location you control. This file sets the work directory and Excel processing options.

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

Starting the MCP server (stdio configuration)

The server is launched as a local process. Use Python to run the server script directly from your file system path.

python C:/path/to/excel-search-mcp/src/server.py

Configuring MCP clients

Claude Desktop and Cursor can be configured to connect to the local MCP server by pointing them at the command that starts the server locally.

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

Security and access controls

Access to files is restricted to the configured work directory. This prevents accidental or malicious access to other parts of your file system. Large files are restricted by size limits to protect memory usage, and permissions are checked before opening a file to ensure only authorized paths are read.

Example features you can use

• List Excel files in the work directory. - Read data from a specific worksheet and convert it to JSON. - Search for text within a workbook and receive the matching cells with coordinates.

Troubleshooting and notes

If the server fails to start, verify that Python is installed and that the path to server.py is correct. Confirm the config.json work directory exists and contains Excel files with supported extensions. Check file permissions and ensure the process has access to the directory. If a search or read operation returns unexpected results, confirm the worksheet name exists and that you are using valid column headers.

Related tooling and endpoints

The server exposes APIs to list files, read worksheet data, and search text. Use these endpoints from your MCP client to integrate Excel data into your AI workflows.

Available tools

list_excel_files

Returns a list of Excel files in the configured work directory with metadata including path, size, and timestamps.

read_excel_data

Reads data from a specified Excel file and worksheet, returning headers, rows, and data types in JSON form.

search_in_excel

Searches for a text term within an Excel file and worksheet, returning matches with row, column, and cell location.