MCP Excel Reader Server

🚀 Excel Reader Server

An MCP (Model Context Protocol) server that provides tools for reading Excel (xlsx) files.

✨ Features

• Read the contents of all worksheets in an Excel file.
• Read the contents of a specific worksheet by its name.
• Read the contents of a specific worksheet by its index.
• Return data in JSON format.
• Handle empty cells and data type conversions.

📦 Installation

Python 3.10 or higher is required.

# Using pip
pip install excel-reader-server

# Using uv (Recommended)
uv pip install excel-reader-server

📚 Dependencies

• mcp >= 1.2.1
• openpyxl >= 3.1.5

💻 Usage Examples

Basic Usage

The server provides three main tools:

1. read_excel

Read the contents of all worksheets in an Excel file.

{
  "file_path": "path/to/your/excel/file.xlsx"
}

2. read_excel_by_sheet_name

Read the contents of a specific worksheet by its name. If no sheet name is provided, the first worksheet will be read.

{
  "file_path": "path/to/your/excel/file.xlsx",
  "sheet_name": "Sheet1"  # Optional parameter
}

3. read_excel_by_sheet_index

Read the contents of a specific worksheet by its index. If no index is provided, the first worksheet (index 0) will be read.

{
  "file_path": "path/to/your/excel/file.xlsx",
  "sheet_index": 0  # Optional parameter
}

Response Format

The server returns data in the following JSON format:

{
  "Sheet1": [
    ["Header1", "Header2", "Header3"],
    ["Value1", "Value2", "Value3"],
    ["Value4", "Value5", "Value6"]
  ]
}

• Each worksheet is represented as a key in the top-level object.
• The worksheet data is an array, where each inner array represents a row.
• All values are converted to strings.
• Empty cells are represented as empty strings.

🔧 Technical Details

Error Handling

The server provides clear error messages for common issues, including:

• File not found
• Invalid sheet name
• Index out of range
• General Excel file reading errors

📄 License

This project is released under the Apache 2 license. For more details, please refer to the LICENSE file.

💪 Contribution

Contributions are welcome! Feel free to submit a Pull Request.