xlwings Excel MCP Server

Instructions

Force close a specific workbook by file path (without saving).

Args:
    filepath: Path to the workbook to force close
    
Returns:
    Dictionary with 'closed' (bool) and 'message' (str)

Implementation Reference

• src/xlwings_mcp/server.py:206-227 (handler)

  MCP tool handler: wrapper that resolves the full path and calls the core force_close_workbook_by_path function, also handles exceptions and logging.

  def force_close_workbook_by_path_tool(
      filepath: str
  ) -> Dict[str, Any]:
      """
      Force close a specific workbook by file path (without saving).
      
      Args:
          filepath: Path to the workbook to force close
          
      Returns:
          Dictionary with 'closed' (bool) and 'message' (str)
      """
      try:
          full_path = get_excel_path(filepath)
          return force_close_workbook_by_path(full_path)
      except Exception as e:
          logger.error(f"Error force closing workbook: {e}")
          return {
              "closed": False,
              "message": f"Failed to force close workbook: {str(e)}"
          }

• src/xlwings_mcp/force_close.py:26-113 (helper)

  Core helper function implementing the force close logic using pywin32 COM to connect to Excel, find the workbook by path, close it without saving, and optionally quit Excel if no workbooks remain.

  def force_close_workbook_by_path(filepath: str) -> Dict[str, Any]:
      """
      Force close a specific workbook from any running Excel process.
      
      Args:
          filepath: Absolute path to the workbook to close
          
      Returns:
          Dictionary with 'closed' (bool) and 'message' (str)
      """
      
      if not PYWIN32_AVAILABLE:
          return {
              "closed": False,
              "message": "Force close not available (pywin32 not installed or not on Windows)"
          }
      
      # Normalize the file path
      target_path = os.path.abspath(filepath).lower()
      
      try:
          # Initialize COM for this thread
          pythoncom.CoInitialize()
          
          found = False
          closed = False
          
          try:
              # Try to connect to running Excel instance
              xl = win32com.client.GetObject(Class="Excel.Application")
              
              # Check all open workbooks
              for wb in xl.Workbooks:
                  try:
                      # Compare full paths (case-insensitive on Windows)
                      wb_path = os.path.abspath(wb.FullName).lower()
                      
                      if wb_path == target_path:
                          logger.info(f"Found workbook to force close: {wb.FullName}")
                          found = True
                          
                          # Force close without saving
                          wb.Close(SaveChanges=False)
                          closed = True
                          logger.info(f"Successfully force closed: {filepath}")
                          break
                          
                  except Exception as e:
                      logger.warning(f"Error checking/closing workbook: {e}")
                      continue
              
              # If no workbooks remain, optionally quit Excel
              if closed and xl.Workbooks.Count == 0:
                  try:
                      xl.Quit()
                      logger.info("Excel application quit (no remaining workbooks)")
                  except:
                      pass
                      
          except Exception as e:
              # No Excel instance running or other COM error
              logger.debug(f"Could not connect to Excel: {e}")
              return {
                  "closed": False,
                  "message": f"No Excel instance found or cannot connect: {str(e)}"
              }
          
          finally:
              # Uninitialize COM
              pythoncom.CoUninitialize()
          
          if not found:
              return {
                  "closed": False,
                  "message": f"Workbook not found in any Excel instance: {filepath}"
              }
          
          return {
              "closed": closed,
              "message": f"Successfully force closed workbook: {filepath}"
          }
          
      except Exception as e:
          logger.error(f"Force close failed for {filepath}: {e}")
          return {
              "closed": False,
              "message": f"Force close failed: {str(e)}"
          }

• src/xlwings_mcp/server.py:25-206 (registration)

  Import of the helper function used by the tool handler.

  from xlwings_mcp.force_close import force_close_workbook_by_path
  
  # Get project root directory path for log file path.
  # When using the stdio transmission method,
  # relative paths may cause log files to fail to create
  # due to the client's running location and permission issues,
  # resulting in the program not being able to run.
  # Thus using os.path.join(ROOT_DIR, "excel-mcp.log") instead.
  
  ROOT_DIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
  LOGS_DIR = os.path.join(ROOT_DIR, "logs")
  os.makedirs(LOGS_DIR, exist_ok=True)
  LOG_FILE = os.path.join(LOGS_DIR, "excel-mcp.log")
  
  # Initialize EXCEL_FILES_PATH variable without assigning a value
  EXCEL_FILES_PATH = None
  
  # xlwings 구현 사용 (openpyxl 마이그레이션 완료)
  
  # Configure logging with rotation to prevent infinite log growth
  from logging.handlers import RotatingFileHandler
  
  logging.basicConfig(
      level=logging.INFO,
      format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
      handlers=[
          # Referring to https://github.com/modelcontextprotocol/python-sdk/issues/409#issuecomment-2816831318
          # The stdio mode server MUST NOT write anything to its stdout that is not a valid MCP message.
          # Use RotatingFileHandler to prevent infinite log growth (5MB max, keep 3 backup files)
          RotatingFileHandler(LOG_FILE, maxBytes=5*1024*1024, backupCount=3)
      ],
  )
  logger = logging.getLogger("excel-mcp")
  logger.info("🚀 Excel MCP Server starting - xlwings 모드 활성화")
  
  # Error message templates for consistent error reporting
  ERROR_TEMPLATES = {
      'SESSION_NOT_FOUND': "SESSION_NOT_FOUND: Session '{session_id}' not found. It may have expired after {ttl} minutes of inactivity. Use open_workbook() to create a new session.",
      'SESSION_TIMEOUT': "SESSION_TIMEOUT: Session '{session_id}' expired at {time}. Create new session with open_workbook()",
      'FILE_LOCKED': "FILE_ACCESS_ERROR: '{filepath}' is locked by another process. Use force_close_workbook_by_path() to force close it first.",
      'FILE_NOT_FOUND': "FILE_NOT_FOUND: '{filepath}' does not exist. Check the path or create a new workbook with create_workbook().",
      'SHEET_NOT_FOUND': "SHEET_NOT_FOUND: Sheet '{sheet_name}' not found in workbook. Available sheets: {sheets}",
      'INVALID_RANGE': "INVALID_RANGE: Range '{range}' is not valid. Use format like 'A1' or 'A1:B10'.",
      'PARAMETER_MISSING': "PARAMETER_MISSING: Either {param1} or {param2} must be provided.",
  }
  
  # Session validation decorator for DRY principle
  def get_validated_session(session_id: str):
      """
      Helper function to validate session_id and return session object.
      Centralizes session validation logic for DRY principle.
      
      Args:
          session_id: Session ID to validate
          
      Returns:
          Session object if valid, error message string if invalid
      """
      if not session_id:
          return ERROR_TEMPLATES['PARAMETER_MISSING'].format(
              param1='session_id', param2='valid session'
          )
      
      session = SESSION_MANAGER.get_session(session_id)
      if not session:
          return ERROR_TEMPLATES['SESSION_NOT_FOUND'].format(
              session_id=session_id, ttl=10
          )
      
      return session
  
  # Initialize FastMCP server
  mcp = FastMCP(
      "excel-mcp",
      instructions="Excel MCP Server for manipulating Excel files"
  )
  
  def get_excel_path(filename: str) -> str:
      """Get full path to Excel file.
      
      Args:
          filename: Name of Excel file
          
      Returns:
          Full path to Excel file
      """
      # If filename is already an absolute path, return it
      if os.path.isabs(filename):
          return filename
  
      # Check if in SSE mode (EXCEL_FILES_PATH is not None)
      if EXCEL_FILES_PATH is None:
          # Must use absolute path
          raise ValueError(f"Invalid filename: {filename}, must be an absolute path when not in SSE mode")
  
      # In SSE mode, if it's a relative path, resolve it based on EXCEL_FILES_PATH
      return os.path.join(EXCEL_FILES_PATH, filename)
  
  # ============================================================================
  # SESSION MANAGEMENT TOOLS (NEW)
  # ============================================================================
  
  @mcp.tool()
  def open_workbook(
      filepath: str,
      visible: bool = False,
      read_only: bool = False
  ) -> Dict[str, Any]:
      """
      Open an Excel workbook and create a session.
      
      Args:
          filepath: Path to Excel file
          visible: Whether to show Excel window (default: False)
          read_only: Whether to open in read-only mode (default: False)
          
      Returns:
          Dictionary with session_id, filepath, visible, read_only, and sheets
      """
      try:
          full_path = get_excel_path(filepath)
          session_id = SESSION_MANAGER.open_workbook(full_path, visible, read_only)
          
          # Get session info
          session = SESSION_MANAGER.get_session(session_id)
          if not session:
              raise WorkbookError(f"Failed to create session for {filepath}")
          
          return {
              "session_id": session_id,
              "filepath": session.filepath,
              "visible": session.visible,
              "read_only": session.read_only,
              "sheets": [sheet.name for sheet in session.workbook.sheets]
          }
          
      except Exception as e:
          logger.error(f"Error opening workbook: {e}")
          raise WorkbookError(f"Failed to open workbook: {str(e)}")
  
  @mcp.tool()
  def close_workbook(
      session_id: str,
      save: bool = True
  ) -> str:
      """
      Close a workbook session.
      
      Args:
          session_id: Session ID from open_workbook
          save: Whether to save changes (default: True)
          
      Returns:
          Success message
      """
      try:
          success = SESSION_MANAGER.close_workbook(session_id, save)
          if not success:
              raise WorkbookError(f"Session {session_id} not found")
          
          return f"Workbook session {session_id} closed successfully"
          
      except Exception as e:
          logger.error(f"Error closing workbook: {e}")
          raise WorkbookError(f"Failed to close workbook: {str(e)}")
  
  @mcp.tool()
  def list_workbooks() -> List[Dict[str, Any]]:
      """
      List all open workbook sessions.
      
      Returns:
          List of session information dictionaries
      """
      try:
          return SESSION_MANAGER.list_sessions()
      except Exception as e:
          logger.error(f"Error listing workbooks: {e}")
          raise WorkbookError(f"Failed to list workbooks: {str(e)}")
  
  @mcp.tool()
  def force_close_workbook_by_path_tool(