Excel MCP Server

Instructions

Read data from Excel worksheet with cell metadata including validation rules.

Args:
    filepath: Path to Excel file
    sheet_name: Name of worksheet
    start_cell: Starting cell (default A1)
    end_cell: Ending cell (optional, auto-expands if not provided)
    preview_only: Whether to return preview only

Returns:  
JSON string containing structured cell data with validation metadata.
Each cell includes: address, value, row, column, and validation info (if any).

Implementation Reference

• src/excel_mcp/server.py:195-236 (handler)

  Main tool handler decorated with @mcp.tool(). Parses arguments, resolves file path, calls the core read_excel_range_with_metadata helper, and returns JSON-formatted result.

  @mcp.tool()
  def read_data_from_excel(
      filepath: str,
      sheet_name: str,
      start_cell: str = "A1",
      end_cell: Optional[str] = None,
      preview_only: bool = False
  ) -> str:
      """
      Read data from Excel worksheet with cell metadata including validation rules.
      
      Args:
          filepath: Path to Excel file
          sheet_name: Name of worksheet
          start_cell: Starting cell (default A1)
          end_cell: Ending cell (optional, auto-expands if not provided)
          preview_only: Whether to return preview only
      
      Returns:  
      JSON string containing structured cell data with validation metadata.
      Each cell includes: address, value, row, column, and validation info (if any).
      """
      try:
          full_path = get_excel_path(filepath)
          from excel_mcp.data import read_excel_range_with_metadata
          result = read_excel_range_with_metadata(
              full_path, 
              sheet_name, 
              start_cell, 
              end_cell
          )
          if not result or not result.get("cells"):
              return "No data found in specified range"
              
          # Return as formatted JSON string
          import json
          return json.dumps(result, indent=2, default=str)
          
      except Exception as e:
          logger.error(f"Error reading data: {e}")
          raise

• src/excel_mcp/data.py:170-280 (helper)

  Core helper function that loads the workbook using openpyxl, parses the cell range, extracts cell values and metadata (including data validation rules), and returns a structured dictionary of cell data used by the handler.

  def read_excel_range_with_metadata(
      filepath: Path | str,
      sheet_name: str,
      start_cell: str = "A1",
      end_cell: Optional[str] = None,
      include_validation: bool = True
  ) -> Dict[str, Any]:
      """Read data from Excel range with cell metadata including validation rules.
      
      Args:
          filepath: Path to Excel file
          sheet_name: Name of worksheet
          start_cell: Starting cell address
          end_cell: Ending cell address (optional)
          include_validation: Whether to include validation metadata
          
      Returns:
          Dictionary containing structured cell data with metadata
      """
      try:
          wb = load_workbook(filepath, read_only=False)
          
          if sheet_name not in wb.sheetnames:
              raise DataError(f"Sheet '{sheet_name}' not found")
              
          ws = wb[sheet_name]
  
          # Parse start cell
          if ':' in start_cell:
              start_cell, end_cell = start_cell.split(':')
              
          # Get start coordinates
          try:
              start_coords = parse_cell_range(f"{start_cell}:{start_cell}")
              if not start_coords or not all(coord is not None for coord in start_coords[:2]):
                  raise DataError(f"Invalid start cell reference: {start_cell}")
              start_row, start_col = start_coords[0], start_coords[1]
          except ValueError as e:
              raise DataError(f"Invalid start cell format: {str(e)}")
  
          # Determine end coordinates
          if end_cell:
              try:
                  end_coords = parse_cell_range(f"{end_cell}:{end_cell}")
                  if not end_coords or not all(coord is not None for coord in end_coords[:2]):
                      raise DataError(f"Invalid end cell reference: {end_cell}")
                  end_row, end_col = end_coords[0], end_coords[1]
              except ValueError as e:
                  raise DataError(f"Invalid end cell format: {str(e)}")
          else:
              # If no end_cell, use the full data range of the sheet
              if ws.max_row == 1 and ws.max_column == 1 and ws.cell(1, 1).value is None:
                  # Handle empty sheet
                  end_row, end_col = start_row, start_col
              else:
                  # Use the sheet's own boundaries, but respect the provided start_cell
                  end_row, end_col = ws.max_row, ws.max_column
                  # If start_cell is 'A1' (default), we should find the true start
                  if start_cell == 'A1':
                      start_row, start_col = ws.min_row, ws.min_column
  
          # Validate range bounds
          if start_row > ws.max_row or start_col > ws.max_column:
              # This case can happen if start_cell is outside the used area on a sheet with data
              # or on a completely empty sheet.
              logger.warning(
                  f"Start cell {start_cell} is outside the sheet's data boundary "
                  f"({get_column_letter(ws.min_column)}{ws.min_row}:{get_column_letter(ws.max_column)}{ws.max_row}). "
                  f"No data will be read."
              )
              return {"range": f"{start_cell}:", "sheet_name": sheet_name, "cells": []}
  
          # Build structured cell data
          range_str = f"{get_column_letter(start_col)}{start_row}:{get_column_letter(end_col)}{end_row}"
          range_data = {
              "range": range_str,
              "sheet_name": sheet_name,
              "cells": []
          }
          
          for row in range(start_row, end_row + 1):
              for col in range(start_col, end_col + 1):
                  cell = ws.cell(row=row, column=col)
                  cell_address = f"{get_column_letter(col)}{row}"
                  
                  cell_data = {
                      "address": cell_address,
                      "value": cell.value,
                      "row": row,
                      "column": col
                  }
                  
                  # Add validation metadata if requested
                  if include_validation:
                      validation_info = get_data_validation_for_cell(ws, cell_address)
                      if validation_info:
                          cell_data["validation"] = validation_info
                      else:
                          cell_data["validation"] = {"has_validation": False}
                  
                  range_data["cells"].append(cell_data)
  
          wb.close()
          return range_data
          
      except DataError as e:
          logger.error(str(e))
          raise
      except Exception as e:
          logger.error(f"Failed to read Excel range with metadata: {e}")
          raise DataError(str(e))