Excel MCP Server

Instructions

Implementation Reference

• src/excel_mcp/server.py:265-277 (handler)

  MCP tool handler decorated with @mcp.tool(). Resolves the full file path using get_excel_path, imports and calls the workbook creation implementation, handles errors, and returns success or error message.

  @mcp.tool()
  def create_workbook(filepath: str) -> str:
      """Create new Excel workbook."""
      try:
          full_path = get_excel_path(filepath)
          from excel_mcp.workbook import create_workbook as create_workbook_impl
          create_workbook_impl(full_path)
          return f"Created workbook at {full_path}"
      except WorkbookError as e:
          return f"Error: {str(e)}"
      except Exception as e:
          logger.error(f"Error creating workbook: {e}")
          raise

• src/excel_mcp/workbook.py:12-34 (helper)

  Core implementation function that creates a new openpyxl Workbook instance, optionally renames the default sheet, ensures directory exists, saves the file, and returns a dictionary with message, active sheet, and workbook object.

  def create_workbook(filepath: str, sheet_name: str = "Sheet1") -> dict[str, Any]:
      """Create a new Excel workbook with optional custom sheet name"""
      try:
          wb = Workbook()
          # Rename default sheet
          if "Sheet" in wb.sheetnames:
              sheet = wb["Sheet"]
              sheet.title = sheet_name
          else:
              wb.create_sheet(sheet_name)
  
          path = Path(filepath)
          path.parent.mkdir(parents=True, exist_ok=True)
          wb.save(str(path))
          return {
              "message": f"Created workbook: {filepath}",
              "active_sheet": sheet_name,
              "workbook": wb
          }
      except Exception as e:
          logger.error(f"Failed to create workbook: {e}")
          raise WorkbookError(f"Failed to create workbook: {e!s}")