Excel MCP Server

Instructions

Write data to Excel worksheet.
Excel formula will write to cell without any verification.

PARAMETERS:  
filepath: Path to Excel file
sheet_name: Name of worksheet to write to
data: List of lists containing data to write to the worksheet, sublists are assumed to be rows
start_cell: Cell to start writing to, default is "A1"

Implementation Reference

• src/excel_mcp/server.py:237-264 (handler)

  MCP tool handler and registration for 'write_data_to_excel'. Resolves filepath and calls the core write_data implementation.

  @mcp.tool()
  def write_data_to_excel(
      filepath: str,
      sheet_name: str,
      data: List[List],
      start_cell: str = "A1",
  ) -> str:
      """
      Write data to Excel worksheet.
      Excel formula will write to cell without any verification.
  
      PARAMETERS:  
      filepath: Path to Excel file
      sheet_name: Name of worksheet to write to
      data: List of lists containing data to write to the worksheet, sublists are assumed to be rows
      start_cell: Cell to start writing to, default is "A1"
    
      """
      try:
          full_path = get_excel_path(filepath)
          result = write_data(full_path, sheet_name, data, start_cell)
          return result["message"]
      except (ValidationError, DataError) as e:
          return f"Error: {str(e)}"
      except Exception as e:
          logger.error(f"Error writing data: {e}")
          raise

• src/excel_mcp/data.py:92-139 (helper)

  Core helper function 'write_data' that handles workbook loading, sheet management, data writing delegation, and saving.

  def write_data(
      filepath: str,
      sheet_name: Optional[str],
      data: Optional[List[List]],
      start_cell: str = "A1",
  ) -> Dict[str, str]:
      """Write data to Excel sheet with workbook handling
      
      Headers are handled intelligently based on context.
      """
      try:
          if not data:
              raise DataError("No data provided to write")
              
          wb = load_workbook(filepath)
  
          # If no sheet specified, use active sheet
          if not sheet_name:
              active_sheet = wb.active
              if active_sheet is None:
                  raise DataError("No active sheet found in workbook")
              sheet_name = active_sheet.title
          elif sheet_name not in wb.sheetnames:
              wb.create_sheet(sheet_name)
  
          ws = wb[sheet_name]
  
          # Validate start cell
          try:
              start_coords = parse_cell_range(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}")
          except ValueError as e:
              raise DataError(f"Invalid start cell format: {str(e)}")
  
          if len(data) > 0:
              _write_data_to_worksheet(ws, data, start_cell)
  
          wb.save(filepath)
          wb.close()
  
          return {"message": f"Data written to {sheet_name}", "active_sheet": sheet_name}
      except DataError as e:
          logger.error(str(e))
          raise
      except Exception as e:
          logger.error(f"Failed to write data: {e}")
          raise DataError(str(e))

• src/excel_mcp/data.py:141-169 (helper)

  Low-level helper that performs the actual cell-by-cell writing to the worksheet.

  def _write_data_to_worksheet(
      worksheet: Worksheet, 
      data: List[List], 
      start_cell: str = "A1",
  ) -> None:
      """Write data to worksheet with intelligent header handling"""
      try:
          if not data:
              raise DataError("No data provided to write")
  
          try:
              start_coords = parse_cell_range(start_cell)
              if not start_coords or not all(x is not None for x 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)}")
  
          # Write data
          for i, row in enumerate(data):
              for j, val in enumerate(row):
                  worksheet.cell(row=start_row + i, column=start_col + j, value=val)
      except DataError as e:
          logger.error(str(e))
          raise
      except Exception as e:
          logger.error(f"Failed to write worksheet data: {e}")
          raise DataError(str(e))