mcp excel reader server

Local 2025-09-01 00:32:23 0
Research and Data @softgridinc-pte-ltd/mcp-excel-reader-server

A Model Context Protocol (MCP) server that provides tools for reading Excel (xlsx) files, enabling extraction of data from entire workbooks or specific sheets with results returned in structured JSON format.

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

Excel Reader Server MCP server

Features

  • Read content from all sheets in an Excel file
  • Read content from a specific sheet by name
  • Read content from a specific sheet by index
  • Returns data in JSON format
  • Handles empty cells and data type conversions

Installation

Requires Python 3.10 or higher.

# 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

The server provides three main tools:

1. read_excel

Reads content from all sheets in an Excel file.

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

2. read_excel_by_sheet_name

Reads content from a specific sheet by name. If no sheet name is provided, reads the first sheet.

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

3. read_excel_by_sheet_index

Reads content from a specific sheet by index. If no index is provided, reads the first sheet (index 0).

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

Response Format

The server returns data in the following JSON format:

{
  "Sheet1": [
    ["Header1", "Header2", "Header3"],
    ["Value1", "Value2", "Value3"],
    ["Value4", "Value5", "Value6"]
  ]
}
  • Each sheet is represented as a key in the top-level object
  • Sheet data is an array of arrays, where each inner array represents a row
  • All values are converted to strings
  • Empty cells are represented as empty strings

Error Handling

The server provides clear error messages for common issues: - 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. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

[
  {
    "description": "Read content from Excel (xlsx) files",
    "inputSchema": {
      "properties": {
        "file_path": {
          "description": "Path to the Excel file",
          "type": "string"
        }
      },
      "required": [
        "file_path"
      ],
      "type": "object"
    },
    "name": "read_excel"
  },
  {
    "description": "Read content from a specific sheet by name in Excel (xlsx) files. Reads first sheet if sheet_name not provided.",
    "inputSchema": {
      "properties": {
        "file_path": {
          "description": "Path to the Excel file",
          "type": "string"
        },
        "sheet_name": {
          "description": "Name of the sheet to read (optional, defaults to first sheet)",
          "type": "string"
        }
      },
      "required": [
        "file_path"
      ],
      "type": "object"
    },
    "name": "read_excel_by_sheet_name"
  },
  {
    "description": "Read content from a specific sheet by index in Excel (xlsx) files. Reads first sheet (index 0) if sheet_index not provided.",
    "inputSchema": {
      "properties": {
        "file_path": {
          "description": "Path to the Excel file",
          "type": "string"
        },
        "sheet_index": {
          "description": "Index of the sheet to read (optional, defaults to 0)",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "file_path"
      ],
      "type": "object"
    },
    "name": "read_excel_by_sheet_index"
  }
]