xlwings Excel MCP Server

Instructions

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

Implementation Reference

• src/xlwings_mcp/server.py:127-164 (handler)

  MCP tool registration and handler for 'open_workbook'. Handles input validation, path resolution via get_excel_path, delegates to SESSION_MANAGER.open_workbook, retrieves session info and returns structured response with session details.

  @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)}")

• src/xlwings_mcp/session.py:271-332 (handler)

  Core implementation of workbook opening in ExcelSessionManager.open_workbook. Manages session limits (LRU eviction), COM initialization, Excel app creation, file locking checks, workbook opening/creation, session object creation and storage, with proper error handling and cleanup.

  def open_workbook(self, filepath: str, visible: bool = False,
                   read_only: bool = False) -> str:
      """Open a workbook and create a new session"""
  
      # Generate session ID
      session_id = str(uuid.uuid4())
  
      # Check if we need to evict old sessions (LRU)
      with self._sessions_lock:
          if len(self._sessions) >= self._max_sessions:
              self._evict_lru_session()
  
      # Ensure COM is initialized for this thread (needed for auto-recovery in worker threads)
      _com_initialize()
  
      try:
          # Log session creation
          logger.debug(f"Creating session {session_id} for {filepath} (visible={visible}, read_only={read_only})")
  
          # Create Excel app instance
          app = xw.App(visible=visible, add_book=False)
          app.display_alerts = False
          app.screen_updating = not visible  # Disable screen updating for hidden instances
          
          # Open workbook
          abs_path = os.path.abspath(filepath)
          
          if os.path.exists(abs_path):
              # Check if file is locked before trying to open
              if not read_only and is_file_locked(abs_path):
                  app.quit()  # Clean up the app we just created
                  raise IOError(f"FILE_ACCESS_ERROR: '{abs_path}' is locked by another process. Use force_close_workbook_by_path() to force close it first.")
              
              wb = app.books.open(abs_path, read_only=read_only)
              logger.debug(f"Opened existing workbook: {abs_path}")
          else:
              # Create new workbook if doesn't exist
              wb = app.books.add()
              Path(abs_path).parent.mkdir(parents=True, exist_ok=True)
              wb.save(abs_path)
              logger.debug(f"Created new workbook: {abs_path}")
          
          # Create session
          session = ExcelSession(session_id, abs_path, app, wb, visible, read_only)
          
          # Store session
          with self._sessions_lock:
              self._sessions[session_id] = session
              logger.info(f"Session {session_id} created for {filepath} (total sessions: {len(self._sessions)})")
          
          return session_id
          
      except Exception as e:
          logger.error(f"Failed to create session for {filepath}: {e}")
          # Clean up on failure
          if 'app' in locals():
              try:
                  app.quit()
              except:
                  pass
          raise

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

  Import of global SESSION_MANAGER singleton used by the open_workbook tool handler.

  from xlwings_mcp.session import SESSION_MANAGER
  from xlwings_mcp.force_close import force_close_workbook_by_path

• src/xlwings_mcp/server.py:102-122 (helper)

  Helper function to resolve relative filepaths to absolute paths based on SSE mode configuration.

  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)