Excel MCP Server

Instructions

Implementation Reference

• src/excel_mcp/server.py:293-322 (handler)

  MCP tool handler for 'create_chart'. Registers the tool with FastMCP and handles input parameters, path resolution, and delegates execution to the implementation while catching specific exceptions.
  @mcp.tool() def create_chart( filepath: str, sheet_name: str, data_range: str, chart_type: str, target_cell: str, title: str = "", x_axis: str = "", y_axis: str = "" ) -> str: """Create chart in worksheet.""" try: full_path = get_excel_path(filepath) result = create_chart_impl( filepath=full_path, sheet_name=sheet_name, data_range=data_range, chart_type=chart_type, target_cell=target_cell, title=title, x_axis=x_axis, y_axis=y_axis ) return result["message"] except (ValidationError, ChartError) as e: return f"Error: {str(e)}" except Exception as e: logger.error(f"Error creating chart: {e}") raise
• src/excel_mcp/chart.py:57-258 (helper)

  Core implementation of chart creation. Loads the workbook, parses data range, creates the specified chart type (line, bar, pie, etc.) using openpyxl, configures titles, axes, data series, styles, and anchors the chart at the target cell.
  def create_chart_in_sheet( filepath: str, sheet_name: str, data_range: str, chart_type: str, target_cell: str, title: str = "", x_axis: str = "", y_axis: str = "", style: Optional[Dict] = None ) -> dict[str, Any]: """Create chart in sheet with enhanced styling options""" # Ensure style dict exists and defaults to showing data labels if style is None: style = {"show_data_labels": True} else: # If caller omitted the flag, default to True style.setdefault("show_data_labels", True) try: wb = load_workbook(filepath) if sheet_name not in wb.sheetnames: logger.error(f"Sheet '{sheet_name}' not found") raise ValidationError(f"Sheet '{sheet_name}' not found") worksheet = wb[sheet_name] # Initialize collections if they don't exist if not hasattr(worksheet, '_drawings'): worksheet._drawings = [] if not hasattr(worksheet, '_charts'): worksheet._charts = [] # Parse the data range if "!" in data_range: range_sheet_name, cell_range = data_range.split("!") if range_sheet_name not in wb.sheetnames: logger.error(f"Sheet '{range_sheet_name}' referenced in data range not found") raise ValidationError(f"Sheet '{range_sheet_name}' referenced in data range not found") else: cell_range = data_range try: start_cell, end_cell = cell_range.split(":") start_row, start_col, end_row, end_col = parse_cell_range(start_cell, end_cell) except ValueError as e: logger.error(f"Invalid data range format: {e}") raise ValidationError(f"Invalid data range format: {str(e)}") # Validate chart type chart_classes = { "line": LineChart, "bar": BarChart, "pie": PieChart, "scatter": ScatterChart, "area": AreaChart } chart_type_lower = chart_type.lower() ChartClass = chart_classes.get(chart_type_lower) if not ChartClass: logger.error(f"Unsupported chart type: {chart_type}") raise ValidationError( f"Unsupported chart type: {chart_type}. " f"Supported types: {', '.join(chart_classes.keys())}" ) chart = ChartClass() # Basic chart settings chart.title = title if hasattr(chart, "x_axis"): chart.x_axis.title = x_axis if hasattr(chart, "y_axis"): chart.y_axis.title = y_axis try: # Create data references if chart_type_lower == "scatter": # For scatter charts, create series for each pair of columns for col in range(start_col + 1, end_col + 1): x_values = Reference( worksheet, min_row=start_row + 1, max_row=end_row, min_col=start_col ) y_values = Reference( worksheet, min_row=start_row + 1, max_row=end_row, min_col=col ) series = Series(y_values, x_values, title_from_data=True) chart.series.append(series) else: # For other chart types data = Reference( worksheet, min_row=start_row, max_row=end_row, min_col=start_col + 1, max_col=end_col ) cats = Reference( worksheet, min_row=start_row + 1, max_row=end_row, min_col=start_col ) chart.add_data(data, titles_from_data=True) chart.set_categories(cats) except Exception as e: logger.error(f"Failed to create chart data references: {e}") raise ChartError(f"Failed to create chart data references: {str(e)}") # Apply style if provided try: if style.get("show_legend", True): chart.legend = Legend() chart.legend.position = style.get("legend_position", "r") else: chart.legend = None if style.get("show_data_labels", False): data_labels = DataLabelList() # Gather optional overrides dlo = style.get("data_label_options", {}) if isinstance(style.get("data_label_options", {}), dict) else {} # Helper to read bool with fallback def _opt(name: str, default: bool) -> bool: return bool(dlo.get(name, default)) # Apply options – Excel will concatenate any that are set to True data_labels.showVal = _opt("show_val", True) data_labels.showCatName = _opt("show_cat_name", False) data_labels.showSerName = _opt("show_ser_name", False) data_labels.showLegendKey = _opt("show_legend_key", False) data_labels.showPercent = _opt("show_percent", False) data_labels.showBubbleSize = _opt("show_bubble_size", False) chart.dataLabels = data_labels if style.get("grid_lines", False): if hasattr(chart, "x_axis"): chart.x_axis.majorGridlines = ChartLines() if hasattr(chart, "y_axis"): chart.y_axis.majorGridlines = ChartLines() except Exception as e: logger.error(f"Failed to apply chart style: {e}") raise ChartError(f"Failed to apply chart style: {str(e)}") # Set chart size chart.width = 15 chart.height = 7.5 # Create drawing and anchor try: drawing = SpreadsheetDrawing() drawing.chart = chart # Validate target cell format if not target_cell or not any(c.isalpha() for c in target_cell) or not any(c.isdigit() for c in target_cell): raise ValidationError(f"Invalid target cell format: {target_cell}") # Create anchor col = column_index_from_string(target_cell[0]) - 1 row = int(target_cell[1:]) - 1 anchor = OneCellAnchor() anchor._from = AnchorMarker(col=col, row=row) drawing.anchor = anchor # Add to worksheet worksheet._drawings.append(drawing) worksheet._charts.append(chart) except ValueError as e: logger.error(f"Invalid target cell: {e}") raise ValidationError(f"Invalid target cell: {str(e)}") except Exception as e: logger.error(f"Failed to create chart drawing: {e}") raise ChartError(f"Failed to create chart drawing: {str(e)}") try: wb.save(filepath) except Exception as e: logger.error(f"Failed to save workbook: {e}") raise ChartError(f"Failed to save workbook with chart: {str(e)}") return { "message": f"{chart_type.capitalize()} chart created successfully", "details": { "type": chart_type, "location": target_cell, "data_range": data_range } } except (ValidationError, ChartError): raise except Exception as e: logger.error(f"Unexpected error creating chart: {e}") raise ChartError(f"Unexpected error creating chart: {str(e)}")
• src/excel_mcp/chart.py:23-34 (schema)

  Enum defining valid chart types for input validation in the create_chart tool.
  class ChartType(str, Enum): """Supported chart types""" LINE = "line" BAR = "bar" PIE = "pie" SCATTER = "scatter" AREA = "area" BUBBLE = "bubble" STOCK = "stock" SURFACE = "surface" RADAR = "radar"
• src/excel_mcp/server.py:24-24 (registration)

  Import of the chart implementation function aliased for use in the handler.
  from excel_mcp.chart import create_chart_in_sheet as create_chart_impl