Browser-Use MCP Server

Instructions

Implementation Reference

• src/mcp_server_browser_use/server.py:179-179 (registration)

  Registers the 'run_browser_agent' tool using the @server.tool() decorator on the FastMCP server instance.

  @server.tool()

• src/mcp_server_browser_use/server.py:179-249 (handler)

  The primary handler function for the 'run_browser_agent' MCP tool. It orchestrates browser/context creation, instantiates BrowserUseAgent with the provided task, executes the agent loop, handles shared resources, logging, errors, and cleanup based on settings, returning the agent's final result.

  @server.tool()
  async def run_browser_agent(ctx: Context, task: str) -> str:
      logger.info(f"Received run_browser_agent task: {task[:100]}...")
      agent_task_id = str(uuid.uuid4())
      final_result = "Error: Agent execution failed."
  
      browser_instance: Optional[CustomBrowser] = None
      context_instance: Optional[CustomBrowserContext] = None
      controller_instance: Optional[CustomController] = None
  
      try:
          async with resource_lock: # Protect shared resource access/creation
              browser_instance, context_instance = await get_browser_and_context()
              # For server, ask_human_callback is likely not interactive, can be None or a placeholder
              controller_instance = await get_controller(ask_human_callback=None)
  
          if not browser_instance or not context_instance or not controller_instance:
               raise RuntimeError("Failed to acquire browser resources or controller.")
  
          main_llm_config = settings.get_llm_config()
          main_llm = internal_llm_provider.get_llm_model(**main_llm_config)
  
          planner_llm = None
          if settings.llm.planner_provider and settings.llm.planner_model_name:
              planner_llm_config = settings.get_llm_config(is_planner=True)
              planner_llm = internal_llm_provider.get_llm_model(**planner_llm_config)
  
          agent_history_json_file = None
          task_history_base_path = settings.agent_tool.history_path
  
          if task_history_base_path:
              task_specific_history_dir = Path(task_history_base_path) / agent_task_id
              task_specific_history_dir.mkdir(parents=True, exist_ok=True)
              agent_history_json_file = str(task_specific_history_dir / f"{agent_task_id}.json")
              logger.info(f"Agent history will be saved to: {agent_history_json_file}")
  
          agent_instance = BrowserUseAgent(
              task=task,
              llm=main_llm,
              browser=browser_instance,
              browser_context=context_instance,
              controller=controller_instance,
              planner_llm=planner_llm,
              max_actions_per_step=settings.agent_tool.max_actions_per_step,
              use_vision=settings.agent_tool.use_vision,
          )
  
          history: AgentHistoryList = await agent_instance.run(max_steps=settings.agent_tool.max_steps)
  
          if agent_history_json_file:
              agent_instance.save_history(agent_history_json_file)
  
          final_result = history.final_result() or "Agent finished without a final result."
          logger.info(f"Agent task completed. Result: {final_result[:100]}...")
  
      except Exception as e:
          logger.error(f"Error in run_browser_agent: {e}\n{traceback.format_exc()}")
          final_result = f"Error: {e}"
      finally:
          if not settings.browser.keep_open and not settings.browser.use_own_browser:
              logger.info("Closing browser resources for this call.")
              if context_instance:
                  await context_instance.close()
              if browser_instance:
                  await browser_instance.close()
              if controller_instance: # Close controller only if not shared
                  await controller_instance.close_mcp_client()
          elif settings.browser.use_own_browser: # Own browser, only close controller if not shared
               if controller_instance and not (settings.browser.keep_open and controller_instance == shared_controller_instance):
                  await controller_instance.close_mcp_client()
      return final_result