Excel MCP Server

Instructions

Implementation Reference

• src/excel_mcp/server.py:141-194 (registration)

  MCP tool registration and wrapper handler for 'format_range'. Uses @mcp.tool() decorator to register the tool and delegates to the core implementation in formatting.py.

  @mcp.tool()
  def format_range(
      filepath: str,
      sheet_name: str,
      start_cell: str,
      end_cell: Optional[str] = None,
      bold: bool = False,
      italic: bool = False,
      underline: bool = False,
      font_size: Optional[int] = None,
      font_color: Optional[str] = None,
      bg_color: Optional[str] = None,
      border_style: Optional[str] = None,
      border_color: Optional[str] = None,
      number_format: Optional[str] = None,
      alignment: Optional[str] = None,
      wrap_text: bool = False,
      merge_cells: bool = False,
      protection: Optional[Dict[str, Any]] = None,
      conditional_format: Optional[Dict[str, Any]] = None
  ) -> str:
      """Apply formatting to a range of cells."""
      try:
          full_path = get_excel_path(filepath)
          from excel_mcp.formatting import format_range as format_range_func
          
          # Convert None values to appropriate defaults for the underlying function
          format_range_func(
              filepath=full_path,
              sheet_name=sheet_name,
              start_cell=start_cell,
              end_cell=end_cell,  # This can be None
              bold=bold,
              italic=italic,
              underline=underline,
              font_size=font_size,  # This can be None
              font_color=font_color,  # This can be None
              bg_color=bg_color,  # This can be None
              border_style=border_style,  # This can be None
              border_color=border_color,  # This can be None
              number_format=number_format,  # This can be None
              alignment=alignment,  # This can be None
              wrap_text=wrap_text,
              merge_cells=merge_cells,
              protection=protection,  # This can be None
              conditional_format=conditional_format  # This can be None
          )
          return "Range formatted successfully"
      except (ValidationError, FormattingError) as e:
          return f"Error: {str(e)}"
      except Exception as e:
          logger.error(f"Error formatting range: {e}")
          raise

• src/excel_mcp/formatting.py:19-249 (handler)

  Core handler function implementing the formatting logic for cell ranges using openpyxl. Applies font, background, borders, alignment, number formats, merging, protection, and conditional formatting.

  def format_range(
      filepath: str,
      sheet_name: str,
      start_cell: str,
      end_cell: Optional[str] = None,
      bold: bool = False,
      italic: bool = False,
      underline: bool = False,
      font_size: Optional[int] = None,
      font_color: Optional[str] = None,
      bg_color: Optional[str] = None,
      border_style: Optional[str] = None,
      border_color: Optional[str] = None,
      number_format: Optional[str] = None,
      alignment: Optional[str] = None,
      wrap_text: bool = False,
      merge_cells: bool = False,
      protection: Optional[Dict[str, Any]] = None,
      conditional_format: Optional[Dict[str, Any]] = None
  ) -> Dict[str, Any]:
      """Apply formatting to a range of cells.
      
      This function handles all Excel formatting operations including:
      - Font properties (bold, italic, size, color, etc.)
      - Cell fill/background color
      - Borders (style and color)
      - Number formatting
      - Alignment and text wrapping
      - Cell merging
      - Protection
      - Conditional formatting
      
      Args:
          filepath: Path to Excel file
          sheet_name: Name of worksheet
          start_cell: Starting cell reference
          end_cell: Optional ending cell reference
          bold: Whether to make text bold
          italic: Whether to make text italic
          underline: Whether to underline text
          font_size: Font size in points
          font_color: Font color (hex code)
          bg_color: Background color (hex code)
          border_style: Border style (thin, medium, thick, double)
          border_color: Border color (hex code)
          number_format: Excel number format string
          alignment: Text alignment (left, center, right, justify)
          wrap_text: Whether to wrap text
          merge_cells: Whether to merge the range
          protection: Cell protection settings
          conditional_format: Conditional formatting rules
          
      Returns:
          Dictionary with operation status
      """
      try:
          # Validate cell references
          if not validate_cell_reference(start_cell):
              raise ValidationError(f"Invalid start cell reference: {start_cell}")
              
          if end_cell and not validate_cell_reference(end_cell):
              raise ValidationError(f"Invalid end cell reference: {end_cell}")
              
          wb = get_or_create_workbook(filepath)
          if sheet_name not in wb.sheetnames:
              raise ValidationError(f"Sheet '{sheet_name}' not found")
              
          sheet = wb[sheet_name]
          
          # Get cell range coordinates
          try:
              start_row, start_col, end_row, end_col = parse_cell_range(start_cell, end_cell)
          except ValueError as e:
              raise ValidationError(f"Invalid cell range: {str(e)}")
          
          # If no end cell specified, use start cell coordinates
          if end_row is None:
              end_row = start_row
          if end_col is None:
              end_col = start_col
              
          # Apply font formatting
          font_args = {
              "bold": bold,
              "italic": italic,
              "underline": 'single' if underline else None,
          }
          if font_size is not None:
              font_args["size"] = font_size
          if font_color is not None:
              try:
                  # Ensure color has FF prefix for full opacity
                  font_color = font_color if font_color.startswith('FF') else f'FF{font_color}'
                  font_args["color"] = Color(rgb=font_color)
              except ValueError as e:
                  raise FormattingError(f"Invalid font color: {str(e)}")
          font = Font(**font_args)
          
          # Apply fill
          fill = None
          if bg_color is not None:
              try:
                  # Ensure color has FF prefix for full opacity
                  bg_color = bg_color if bg_color.startswith('FF') else f'FF{bg_color}'
                  fill = PatternFill(
                      start_color=Color(rgb=bg_color),
                      end_color=Color(rgb=bg_color),
                      fill_type='solid'
                  )
              except ValueError as e:
                  raise FormattingError(f"Invalid background color: {str(e)}")
          
          # Apply borders
          border = None
          if border_style is not None:
              try:
                  border_color = border_color if border_color else "000000"
                  border_color = border_color if border_color.startswith('FF') else f'FF{border_color}'
                  side = Side(
                      style=border_style,
                      color=Color(rgb=border_color)
                  )
                  border = Border(
                      left=side,
                      right=side,
                      top=side,
                      bottom=side
                  )
              except ValueError as e:
                  raise FormattingError(f"Invalid border settings: {str(e)}")
              
          # Apply alignment
          align = None
          if alignment is not None or wrap_text:
              try:
                  align = Alignment(
                      horizontal=alignment,
                      vertical='center',
                      wrap_text=wrap_text
                  )
              except ValueError as e:
                  raise FormattingError(f"Invalid alignment settings: {str(e)}")
              
          # Apply protection
          protect = None
          if protection is not None:
              try:
                  protect = Protection(**protection)
              except ValueError as e:
                  raise FormattingError(f"Invalid protection settings: {str(e)}")
              
          # Apply formatting to range
          for row in range(start_row, end_row + 1):
              for col in range(start_col, end_col + 1):
                  cell = sheet.cell(row=row, column=col)
                  cell.font = font
                  if fill is not None:
                      cell.fill = fill
                  if border is not None:
                      cell.border = border
                  if align is not None:
                      cell.alignment = align
                  if protect is not None:
                      cell.protection = protect
                  if number_format is not None:
                      cell.number_format = number_format
                      
          # Merge cells if requested
          if merge_cells and end_cell:
              try:
                  range_str = f"{start_cell}:{end_cell}"
                  sheet.merge_cells(range_str)
              except ValueError as e:
                  raise FormattingError(f"Failed to merge cells: {str(e)}")
              
          # Apply conditional formatting
          if conditional_format is not None:
              range_str = f"{start_cell}:{end_cell}" if end_cell else start_cell
              rule_type = conditional_format.get('type')
              if not rule_type:
                  raise FormattingError("Conditional format type not specified")
                  
              params = conditional_format.get('params', {})
              
              # Handle fill parameter for cell_is rule
              if rule_type == 'cell_is' and 'fill' in params:
                  fill_params = params['fill']
                  if isinstance(fill_params, dict):
                      try:
                          fill_color = fill_params.get('fgColor', 'FFC7CE')  # Default to light red
                          fill_color = fill_color if fill_color.startswith('FF') else f'FF{fill_color}'
                          params['fill'] = PatternFill(
                              start_color=fill_color,
                              end_color=fill_color,
                              fill_type='solid'
                          )
                      except ValueError as e:
                          raise FormattingError(f"Invalid conditional format fill color: {str(e)}")
              
              try:
                  if rule_type == 'color_scale':
                      rule = ColorScaleRule(**params)
                  elif rule_type == 'data_bar':
                      rule = DataBarRule(**params)
                  elif rule_type == 'icon_set':
                      rule = IconSetRule(**params)
                  elif rule_type == 'formula':
                      rule = FormulaRule(**params)
                  elif rule_type == 'cell_is':
                      rule = CellIsRule(**params)
                  else:
                      raise FormattingError(f"Invalid conditional format type: {rule_type}")
                      
                  sheet.conditional_formatting.add(range_str, rule)
              except Exception as e:
                  raise FormattingError(f"Failed to apply conditional formatting: {str(e)}")
              
          wb.save(filepath)
          
          range_str = f"{start_cell}:{end_cell}" if end_cell else start_cell
          return {
              "message": f"Applied formatting to range {range_str}",
              "range": range_str
          }
          
      except (ValidationError, FormattingError) as e:
          logger.error(str(e))
          raise
      except Exception as e:
          logger.error(f"Failed to apply formatting: {e}")
          raise FormattingError(str(e))