xlwings Excel MCP Server

Instructions

Implementation Reference

• src/xlwings_mcp/server.py:503-551 (handler)

  Primary MCP tool handler for 'create_workbook'. Decorated with @mcp.tool(). Dispatches to session-based or legacy filepath creation logic.
  @mcp.tool() def create_workbook( session_id: Optional[str] = None, filepath: Optional[str] = None ) -> str: """ Create new Excel workbook. Args: session_id: Session ID for creating workbook in existing session (optional) filepath: Path to create new Excel file (legacy, deprecated) Note: Use session_id for better performance. filepath parameter is deprecated. """ try: # Support both new (session_id) and old (filepath) API if session_id: # New API: use session (though this is less common for creating new workbooks) session = SESSION_MANAGER.get_session(session_id) if not session: return f"Error: Session {session_id} not found. Please open the workbook first using open_workbook()." with session.lock: from xlwings_mcp.xlwings_impl.workbook_xlw import create_workbook_xlw_with_wb result = create_workbook_xlw_with_wb(session.workbook) return result.get("message", "Workbook created successfully") if "error" not in result else f"Error: {result['error']}" elif filepath: # Legacy API: backwards compatibility logger.warning("Using deprecated filepath parameter. Please use session_id instead.") full_path = get_excel_path(filepath) from xlwings_mcp.workbook import create_workbook as create_workbook_impl create_workbook_impl(full_path) return f"Created workbook at {full_path}" else: return ERROR_TEMPLATES['PARAMETER_MISSING'].format( param1='session_id', param2='filepath' ) except WorkbookError as e: return f"Error: {str(e)}" except Exception as e: logger.error(f"Error creating workbook: {e}") raise @mcp.tool() def create_worksheet( session_id: str, sheet_name: str
• src/xlwings_mcp/xlwings_impl/workbook_xlw.py:125-155 (helper)

  Core xlwings implementation for creating a new workbook from filepath (used by legacy path in handler).
  def create_workbook_xlw( filepath: str, sheet_name: Optional[str] = None ) -> Dict[str, Any]: """xlwings를 사용한 새 워크북 생성 Args: filepath: 생성할 파일 경로 sheet_name: 기본 시트명 (optional, defaults to Excel's default) Returns: 생성 결과 딕셔너리 """ try: # Use Excel's default sheet name if not provided if not sheet_name: sheet_name = "Sheet1" # Excel's default # Excel context로 새 워크북 생성 with excel_context(filepath, create_if_not_exists=True, sheet_name=sheet_name) as wb: # 워크북이 이미 저장되었으므로 추가 작업 없음 return { "message": f"Created workbook: {filepath}", "filepath": filepath, "active_sheet": sheet_name } except Exception as e: logger.error(f"xlwings 워크북 생성 실패: {e}") return {"error": f"Failed to create workbook: {str(e)}"}
• src/xlwings_mcp/workbook.py:13-18 (helper)

  Public wrapper function for create_workbook_xlw, used by legacy path in MCP handler. Raises WorkbookError on failure.
  def create_workbook(filepath: str, sheet_name: str = "Sheet1") -> dict[str, Any]: """Create a new Excel workbook with optional custom sheet name""" result = create_workbook_xlw(filepath, sheet_name) if "error" in result: raise WorkbookError(result["error"]) return result
• src/xlwings_mcp/xlwings_impl/workbook_xlw.py:223-255 (helper)

  Session-based helper for configuring an existing workbook object (used by session_id path in MCP handler).
  def create_workbook_xlw_with_wb(wb, sheet_name: Optional[str] = None) -> Dict[str, Any]: """Session-based version using existing workbook object. Args: wb: Workbook object from session sheet_name: 기본 시트명 (optional, defaults to Excel's default) Returns: 생성 결과 딕셔너리 """ try: # This is a special case - when wb is provided, we might add sheets or modify it # For a new workbook, typically the workbook creation was handled in session setup # But we can still configure it here if sheet_name and wb.sheets: # Rename the first sheet if sheet_name is provided first_sheet = wb.sheets[0] if first_sheet.name != sheet_name: first_sheet.name = sheet_name # Save the workbook to ensure changes persist wb.save() return { "message": f"Workbook configured successfully", "active_sheet": wb.sheets[0].name if wb.sheets else None, "sheet_count": len(wb.sheets) } except Exception as e: logger.error(f"xlwings 워크북 설정 실패: {e}") return {"error": f"Failed to configure workbook: {str(e)}"}