Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

Refactor documentation structure and add new sections

Magnus Müllerc57ca023aa24
diff --git a/docs/customize/hooks.mdx b/docs/customize/hooks.mdx
deleted file mode 100644
index a56cf66b8..000000000
--- a/docs/customize/hooks.mdx
+++ /dev/null
@@ -1,382 +0,0 @@
----
-title: "Lifecycle Hooks"
-description: "Customize agent behavior with lifecycle hooks"
-icon: "Wrench"
-author: "Carlos A. Planchón"
-mode: "wide"
----
-
-Browser-Use provides lifecycle hooks that allow you to execute custom code at specific points during the agent's execution.
-Hook functions can be used to read and modify agent state while running, implement custom logic, change configuration, integrate the Agent with external applications.
-
-## Available Hooks
-
-Currently, Browser-Use provides the following hooks:
-
-| Hook | Description | When it's called |
-| --------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `on_step_start` | Executed at the beginning of each agent step | Before the agent processes the current state and decides on the next action |
-| `on_step_end` | Executed at the end of each agent step | After the agent has executed all the actions for the current step, before it starts the next step |
-
-```python
-await agent.run(on_step_start=..., on_step_end=...)
-```
-
-Each hook should be an `async` callable function that accepts the `agent` instance as its only parameter.
-
-### Basic Example
-
-```python
-from browser_use import Agent, ChatOpenAI
-
-
-async def my_step_hook(agent: Agent):
- # inside a hook you can access all the state and methods under the Agent object:
- # agent.settings, agent.state, agent.task
- # agent.tools, agent.llm, agent.browser_session
- # agent.pause(), agent.resume(), agent.add_new_task(...), etc.
-
- # You also have direct access to the browser state
- state = await agent.browser_session.get_browser_state_summary()
-
- current_url = state.url
- visit_log = agent.history.urls()
- previous_url = visit_log[-2] if len(visit_log) >= 2 else None
- print(f"Agent was last on URL: {previous_url} and is now on {current_url}")
-
- # Example: listen for events on the page, interact with the DOM, run JS directly, etc.
- await page.on('domcontentloaded', lambda: print('page navigated to a new url...'))
- await page.locator("css=form > input[type=submit]").click()
- await page.evaluate('() => alert(1)')
- await page.browser.new_tab
- await agent.browser_session.session.context.add_init_script('/* some JS to run on every page */')
-
- # Example: monitor or intercept all network requests
- async def handle_request(route):
- # Print, modify, block, etc. do anything to the requests here
- # https://playwright.dev/python/docs/network#handle-requests
- print(route.request, route.request.headers)
- await route.continue_(headers=route.request.headers)
- await page.route("**/*", handle_route)
-
- # Example: pause agent execution and resume it based on some custom code
- if '/completed' in current_url:
- agent.pause()
- Path('result.txt').write_text(await page.content())
- input('Saved "completed" page content to result.txt, press [Enter] to resume...')
- agent.resume()
-
-agent = Agent(
- task="Search for the latest news about AI",
- llm=ChatOpenAI(model="gpt-4.1-mini"),
-)
-
-await agent.run(
- on_step_start=my_step_hook,
- # on_step_end=...
- max_steps=10
-)
-```
-
-## Data Available in Hooks
-
-When working with agent hooks, you have access to the entire `Agent` instance. Here are some useful data points you can access:
-
-- `agent.task` lets you see what the main task is, `agent.add_new_task(...)` lets you queue up a new one
-- `agent.tools` give access to the `Tools()` object and `Registry()` containing the available actions
- - `agent.tools.registry.execute_action('click_element_by_index', {'index': 123}, browser_session=agent.browser_session)`
-- `agent.context` lets you access any user-provided context object passed in to `Agent(context=...)`
-- `agent.sensitive_data` contains the sensitive data dict, which can be updated in-place to add/remove/modify items
-- `agent.settings` contains all the configuration options passed to the `Agent(...)` at init time
-- `agent.llm` gives direct access to the main LLM object (e.g. `ChatOpenAI`)
-- `agent.state` gives access to lots of internal state, including agent thoughts, outputs, actions, etc.
-- `agent.history` gives access to historical data from the agent's execution:
- - `agent.history.model_thoughts()`: Reasoning from Browser Use's model.
- - `agent.history.model_outputs()`: Raw outputs from the Browser Use's model.
- - `agent.history.model_actions()`: Actions taken by the agent
- - `agent.history.extracted_content()`: Content extracted from web pages
- - `agent.history.urls()`: URLs visited by the agent
-- `agent.browser_session` gives direct access to the `Browser()` and CDP interface
- - `agent.browser_session.agent_focus`: Get the current CDP session the agent is focused on
- - `agent.browser_session.get_or_create_cdp_session()`: Get the current CDP session for browser interaction
- - `agent.browser_session.get_tabs()`: Get all tabs currently open
- - `agent.browser_session.get_page_html()`: Current page HTML
- - `agent.browser_session.take_screenshot()`: Screenshot of the current page
-
-## Tips for Using Hooks
-
-- **Avoid blocking operations**: Since hooks run in the same execution thread as the agent, try to keep them efficient or use asynchronous patterns.
-- **Handle exceptions**: Make sure your hook functions handle exceptions gracefully to prevent interrupting the agent's main flow.
-- **Use custom actions instead**: hooks are fairly advanced, most things can be implemented with [custom action functions](/customize/custom-functions) instead
-
----
-
-## Complex Example: Agent Activity Recording System
-
-This comprehensive example demonstrates a complete implementation for recording and saving Browser-Use agent activity, consisting of both server and client components.
-
-### Setup Instructions
-
-To use this example, you'll need to:
-
-1. Set up the required dependencies:
-
- ```bash
- pip install fastapi uvicorn prettyprinter pyobjtojson dotenv browser-use
- ```
-
-2. Create two separate Python files:
-
- - `api.py` - The FastAPI server component
- - `client.py` - The Browser-Use agent with recording hook
-
-3. Run both components:
- - Start the API server first: `python api.py`
- - Then run the client: `python client.py`
-
-### Server Component (api.py)
-
-The server component handles receiving and storing the agent's activity data:
-
-```python
-#!/usr/bin/env python3
-
-#
-# FastAPI API to record and save Browser-Use activity data.
-# Save this code to api.py and run with `python api.py`
-#
-
-import json
-import base64
-from pathlib import Path
-
-from fastapi import FastAPI, Request
-import prettyprinter
-import uvicorn
-
-prettyprinter.install_extras()
-
-# Utility function to save screenshots
-def b64_to_png(b64_string: str, output_file):
- """
- Convert a Base64-encoded string to a PNG file.
-
- :param b64_string: A string containing Base64-encoded data
- :param output_file: The path to the output PNG file
- """
- with open(output_file, "wb") as f:
- f.write(base64.b64decode(b64_string))
-
-# Initialize FastAPI app
-app = FastAPI()
-
-
[email protected]("/post_agent_history_step")
-async def post_agent_history_step(request: Request):
- data = await request.json()
- prettyprinter.cpprint(data)
-
- # Ensure the "recordings" folder exists using pathlib
- recordings_folder = Path("recordings")
- recordings_folder.mkdir(exist_ok=True)
-
- # Determine the next file number by examining existing .json files
- existing_numbers = []
- for item in recordings_folder.iterdir():
- if item.is_file() and item.suffix == ".json":
- try:
- file_num = int(item.stem)
- existing_numbers.append(file_num)
- except ValueError:
- # In case the file name isn't just a number
- pass
-
- if existing_numbers:
- next_number = max(existing_numbers) + 1
- else:
- next_number = 1
-
- # Construct the file path
- file_path = recordings_folder / f"{next_number}.json"
-
- # Save the JSON data to the file
- with file_path.open("w") as f:
- json.dump(data, f, indent=2)
-
- # Optionally save screenshot if needed
- # if "website_screenshot" in data and data["website_screenshot"]:
- # screenshot_folder = Path("screenshots")
- # screenshot_folder.mkdir(exist_ok=True)
- # b64_to_png(data["website_screenshot"], screenshot_folder / f"{next_number}.png")
-
- return {"status": "ok", "message": f"Saved to {file_path}"}
-
-if __name__ == "__main__":
- print("Starting Browser-Use recording API on http://0.0.0.0:9000")
- uvicorn.run(app, host="0.0.0.0", port=9000)
-```
-
-### Client Component (client.py)
-
-The client component runs the Browser-Use agent with a recording hook:
-
-```python
-#!/usr/bin/env python3
-
-#
-# Client to record and save Browser-Use activity.
-# Save this code to client.py and run with `python client.py`
-#
-
-import asyncio
-import requests
-from dotenv import load_dotenv
-from pyobjtojson import obj_to_json
-from browser_use.llm import ChatOpenAI
-from browser_use import Agent
-
-# Load environment variables (for API keys)
-load_dotenv()
-
-
-def send_agent_history_step(data):
- """Send the agent step data to the recording API"""
- url = "http://127.0.0.1:9000/post_agent_history_step"
- response = requests.post(url, json=data)
- return response.json()
-
-
-async def record_activity(agent_obj):
- """Hook function that captures and records agent activity at each step"""
- website_html = None
- website_screenshot = None
- urls_json_last_elem = None
- model_thoughts_last_elem = None
- model_outputs_json_last_elem = None
- model_actions_json_last_elem = None
- extracted_content_json_last_elem = None
-
- print('--- ON_STEP_START HOOK ---')
-
- # Capture current page state
- website_html = await agent_obj.browser_session.get_page_html()
- website_screenshot = await agent_obj.browser_session.take_screenshot()
-
- # Make sure we have state history
- if hasattr(agent_obj, "state"):
- history = agent_obj.state.history
- else:
- history = None
- print("Warning: Agent has no state history")
- return
-
- # Process model thoughts
- model_thoughts = obj_to_json(
- obj=history.model_thoughts(),
- check_circular=False
- )
- if len(model_thoughts) > 0:
- model_thoughts_last_elem = model_thoughts[-1]
-
- # Process model outputs
- model_outputs = agent_obj.state.history.model_outputs()
- model_outputs_json = obj_to_json(
- obj=model_outputs,
- check_circular=False
- )
- if len(model_outputs_json) > 0:
- model_outputs_json_last_elem = model_outputs_json[-1]
-
- # Process model actions
- model_actions = agent_obj.state.history.model_actions()
- model_actions_json = obj_to_json(
- obj=model_actions,
- check_circular=False
- )
- if len(model_actions_json) > 0:
- model_actions_json_last_elem = model_actions_json[-1]
-
- # Process extracted content
- extracted_content = agent_obj.state.history.extracted_content()
- extracted_content_json = obj_to_json(
- obj=extracted_content,
- check_circular=False
- )
- if len(extracted_content_json) > 0:
- extracted_content_json_last_elem = extracted_content_json[-1]
-
- # Process URLs
- urls = agent_obj.state.history.urls()
- urls_json = obj_to_json(
- obj=urls,
- check_circular=False
- )
- if len(urls_json) > 0:
- urls_json_last_elem = urls_json[-1]
-
- # Create a summary of all data for this step
- model_step_summary = {
- "website_html": website_html,
- "website_screenshot": website_screenshot,
- "url": urls_json_last_elem,
- "model_thoughts": model_thoughts_last_elem,
- "model_outputs": model_outputs_json_last_elem,
- "model_actions": model_actions_json_last_elem,
- "extracted_content": extracted_content_json_last_elem
- }
-
- print("--- MODEL STEP SUMMARY ---")
- print(f"URL: {urls_json_last_elem}")
-
- # Send data to the API
- result = send_agent_history_step(data=model_step_summary)
- print(f"Recording API response: {result}")
-
-
-async def run_agent():
- """Run the Browser-Use agent with the recording hook"""
- agent = Agent(
- task="Compare the price of gpt-4o and DeepSeek-V3",
- llm=ChatOpenAI(model="gpt-4.1-mini"),
- )
-
- try:
- print("Starting Browser-Use agent with recording hook")
- await agent.run(
- on_step_start=record_activity,
- max_steps=30
- )
- except Exception as e:
- print(f"Error running agent: {e}")
-
-
-if __name__ == "__main__":
- # Check if API is running
- try:
- requests.get("http://127.0.0.1:9000")
- print("Recording API is available")
- except:
- print("Warning: Recording API may not be running. Start api.py first.")
-
- # Run the agent
- asyncio.run(run_agent())
-```
-
-Contribution by Carlos A. Planchón.
-
-### Working with the Recorded Data
-
-After running the agent, you'll find the recorded data in the `recordings` directory. Here's how you can use this data:
-
-1. **View recorded sessions**: Each JSON file contains a snapshot of agent activity for one step
-2. **Extract screenshots**: You can modify the API to save screenshots separately
-3. **Analyze agent behavior**: Use the recorded data to study how the agent navigates websites
-
-### Extending the Example
-
-You can extend this recording system in several ways:
-
-1. **Save screenshots separately**: Uncomment the screenshot saving code in the API
-2. **Add a web dashboard**: Create a simple web interface to view recorded sessions
-3. **Add session IDs**: Modify the API to group steps by agent session
-4. **Add filtering**: Implement filters to record only specific types of actions
diff --git a/docs/customize/mcp-client.mdx b/docs/customize/mcp-client.mdx
deleted file mode 100644
index e3299c79b..000000000
--- a/docs/customize/mcp-client.mdx
+++ /dev/null
@@ -1,252 +0,0 @@
----
-title: "MCP Client"
-description: "Connect external MCP servers to extend browser-use with additional tools and integrations"
-icon: "plug"
-mode: "wide"
----
-
-The MCP (Model Context Protocol) client allows browser-use agents to connect to external MCP servers, automatically exposing their tools as actions.
-
-<Note>
- MCP is an open protocol for integrating LLMs with external data sources and tools. Learn more at [modelcontextprotocol.io](https://modelcontextprotocol.io).
-</Note>
-
-<Info>
- Looking to expose browser-use as an MCP server instead? See [MCP Server](/customize/mcp-server).
-</Info>
-
-## Installation
-
-```bash
-uv pip install "browser-use[cli]"
-```
-
-## Quick Start
-
-```python
-import os
-from browser_use import Agent, Tools
-from browser_use.mcp.client import MCPClient
-
-# Create tools
-tools = Tools()
-
-# Connect to MCP server
-mcp_client = MCPClient(
- server_name="filesystem",
- command="npx",
- args=["@modelcontextprotocol/server-filesystem", "/path/to/files"]
-)
-
-# Connect and register
-await mcp_client.connect()
-await mcp_client.register_to_tools(tools)
-
-# Agent can now use filesystem tools
-agent = Agent(
- task="Read the README.md file",
- tools=tools
-)
-await agent.run()
-
-# Clean up
-await mcp_client.disconnect()
-```
-
-## API Reference
-
-### MCPClient
-
-```python
-class MCPClient:
- def __init__(
- self,
- server_name: str,
- command: str,
- args: list[str] | None = None,
- env: dict[str, str] | None = None,
- ) -> None
-```
-
-**Parameters:**
-- `server_name`: Name of the MCP server (for logging)
-- `command`: Command to start the server (e.g., `"npx"`)
-- `args`: Arguments for the command
-- `env`: Environment variables for the server
-
-**Key Methods:**
-
-```python
-# Connect to server
-await mcp_client.connect()
-
-# Register tools to tools
-await mcp_client.register_to_tools(
- tools,
- tool_filter=['read_file', 'write_file'], # Optional
- prefix='fs_' # Optional prefix
-)
-
-# Disconnect
-await mcp_client.disconnect()
-```
-
-### Context Manager Usage
-
-```python
-async with MCPClient(
- server_name="github",
- command="npx",
- args=["@modelcontextprotocol/server-github"],
- env={"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")}
-) as client:
- await client.register_to_tools(tools)
- await agent.run()
-# Automatically disconnected
-```
-
-## Common MCP Servers
-
-### Filesystem
-```python
-MCPClient(
- server_name="filesystem",
- command="npx",
- args=["@modelcontextprotocol/server-filesystem", "/path"]
-)
-```
-
-### PostgreSQL
-```python
-MCPClient(
- server_name="postgres",
- command="npx",
- args=["@modelcontextprotocol/server-postgres", "postgresql://localhost/db"]
-)
-```
-
-### GitHub
-```python
-MCPClient(
- server_name="github",
- command="npx",
- args=["@modelcontextprotocol/server-github"],
- env={"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")}
-)
-```
-
-## Multiple Servers
-
-Connect multiple servers with prefixes to avoid conflicts:
-
-```python
-# Filesystem server
-fs_client = MCPClient(
- server_name="filesystem",
- command="npx",
- args=["@modelcontextprotocol/server-filesystem", "."]
-)
-await fs_client.connect()
-await fs_client.register_to_tools(tools, prefix="fs_")
-
-# GitHub server
-gh_client = MCPClient(
- server_name="github",
- command="npx",
- args=["@modelcontextprotocol/server-github"],
- env={"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")}
-)
-await gh_client.connect()
-await gh_client.register_to_tools(tools, prefix="gh_")
-
-# Agent can use both
-agent = Agent(
- task="Read README.md and create a GitHub issue",
- tools=tools
-)
-await agent.run()
-
-# Clean up
-await fs_client.disconnect()
-await gh_client.disconnect()
-```
-
-## Tool Filtering
-
-Register only specific tools:
-
-```python
-await mcp_client.register_to_tools(
- tools,
- tool_filter=['read_file', 'list_directory']
-)
-```
-
-## Custom MCP Server
-
-Create your own MCP server:
-
-```python
-# my_server.py
-import mcp.server.stdio
-import mcp.types as types
-from mcp.server import Server
-
-server = Server("custom-tools")
-
-async def handle_list_tools() -> list[types.Tool]:
- return [
- types.Tool(
- name="calculate",
- description="Perform calculation",
- inputSchema={
- "type": "object",
- "properties": {
- "expression": {"type": "string"}
- },
- "required": ["expression"]
- }
- )
- ]
-
-async def handle_call_tool(name: str, arguments: dict) -> list[types.TextContent]:
- if name == "calculate":
- result = eval(arguments["expression"])
- return [types.TextContent(type="text", text=str(result))]
- return []
-
-# Run server
-async def main():
- async with mcp.server.stdio.stdio_server() as (read, write):
- await server.run(read, write, ...)
-
-if __name__ == "__main__":
- import asyncio
- asyncio.run(main())
-```
-
-Connect custom server:
-
-```python
-custom_client = MCPClient(
- server_name="custom",
- command="python",
- args=["my_server.py"]
-)
-```
-
-## Best Practices
-
-1. **Always disconnect** when done
-2. **Use prefixes** when connecting multiple servers
-3. **Filter tools** to limit capabilities
-4. **Use context managers** for automatic cleanup
-
-
-## See Also
-
-- [MCP Server](/customize/mcp-server) - Expose browser-use as an MCP server
-- [Custom Functions](/customize/custom-functions) - Write custom actions directly
-- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification
diff --git a/docs/customize/mcp-server.mdx b/docs/customize/mcp-server.mdx
deleted file mode 100644
index 0f2a2a9c4..000000000
--- a/docs/customize/mcp-server.mdx
+++ /dev/null
@@ -1,436 +0,0 @@
----
-title: "MCP Server"
-description: "Expose browser-use capabilities as an MCP server for AI assistants like Claude Desktop"
-icon: "server"
-mode: "wide"
----
-
-The MCP server exposes browser-use's browser automation capabilities as tools that can be used by AI assistants like Claude Desktop. This allows external MCP clients to control browsers, navigate websites, extract content, and perform automated tasks.
-
-<Note>
- This is the opposite of the [MCP Client](/customize/mcp-client). The MCP client lets browser-use connect to external MCP servers, while this MCP server lets external AI assistants connect to browser-use.
-</Note>
-
-## Overview
-
-The MCP server acts as a bridge between MCP-compatible AI assistants and browser-use:
-
-```mermaid
-graph LR
- A[Claude Desktop] -->|MCP Protocol| B[Browser-use MCP Server]
- B --> C[Browser]
- B --> D[Tools]
- B --> E[FileSystem]
- C --> F[Playwright Browser]
-
- style B fill:#f9f,stroke:#333,stroke-width:2px
-```
-
-## Installation
-
-```bash
-uv pip install "browser-use[cli]"
-```
-
-## Quick Start
-
-### 1. Configure Claude Desktop
-
-Add browser-use to your Claude Desktop configuration:
-
-<Tabs>
- <Tab title="macOS">
- Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
- ```json
- {
- "mcpServers": {
- "browser-use": {
- "command": "uvx",
- "args": ["browser-use[cli]", "--mcp"],
- "env": {
- "OPENAI_API_KEY": "sk-..." // Optional: for content extraction
- }
- }
- }
- }
- ```
- </Tab>
- <Tab title="Windows">
- Edit `%APPDATA%\Claude\claude_desktop_config.json`:
- ```json
- {
- "mcpServers": {
- "browser-use": {
- "command": "uvx",
- "args": ["browser-use[cli]", "--mcp"],
- "env": {
- "OPENAI_API_KEY": "sk-..." // Optional: for content extraction
- }
- }
- }
- }
- ```
- </Tab>
-</Tabs>
-
-### 2. Restart Claude Desktop
-
-The browser-use tools will appear in Claude's tools menu (🔌 icon).
-
-### 3. Use Browser Automation
-
-Ask Claude to perform browser tasks:
-- "Navigate to example.com and describe what you see"
-- "Search for 'browser automation' on Google"
-- "Fill out the contact form on this website"
-
-## API Reference
-
-### Available Tools
-
-The MCP server exposes the following tools to MCP clients:
-
-#### Navigation Tools
-
-##### `browser_navigate`
-
-Navigate to a URL.
-
-```typescript
-browser_navigate(url: string, new_tab?: boolean): string
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `url` | `string` | Yes | URL to navigate to |
-| `new_tab` | `boolean` | No | Open in new tab (default: false) |
-
-**Returns:** Success message with URL
-
-##### `browser_go_back`
-
-Navigate back in browser history.
-
-```typescript
-browser_go_back(): string
-```
-
-**Returns:** "Navigated back"
-
-#### Interaction Tools
-
-##### `browser_click`
-
-Click an element by index.
-
-```typescript
-browser_click(index: number, new_tab?: boolean): string
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `index` | `number` | Yes | Element index from browser state |
-| `new_tab` | `boolean` | No | Open link in new tab (default: false) |
-
-**Returns:** Success message indicating click action
-
-**Note:** When `new_tab` is true:
-- For links: Extracts href and opens in new tab
-- For other elements: Uses Cmd/Ctrl+Click
-
-##### `browser_type`
-
-Type text into an input field.
-
-```typescript
-browser_type(index: number, text: string): string
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `index` | `number` | Yes | Element index from browser state |
-| `text` | `string` | Yes | Text to type |
-
-**Returns:** Success message with typed text
-
-##### `browser_scroll`
-
-Scroll the page.
-
-```typescript
-browser_scroll(direction?: "up" | "down"): string
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `direction` | `"up" \| "down"` | No | Scroll direction (default: "down") |
-
-**Returns:** "Scrolled {direction}"
-
-#### State & Content Tools
-
-##### `browser_get_state`
-
-Get current browser state with all interactive elements.
-
-```typescript
-browser_get_state(include_screenshot?: boolean): string
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `include_screenshot` | `boolean` | No | Include base64 screenshot (default: false) |
-
-**Returns:** JSON string containing:
-```json
-{
- "url": "current page URL",
- "title": "page title",
- "tabs": [{"url": "...", "title": "..."}],
- "interactive_elements": [
- {
- "index": 0,
- "tag": "button",
- "text": "element text (max 100 chars)",
- "placeholder": "if present",
- "href": "if link"
- }
- ],
- "screenshot": "base64 if requested"
-}
-```
-
-The interactive elements include all clickable and interactive elements on the page, with their:
-- `index`: Used to reference the element in other commands (click, type)
-- `tag`: HTML tag name (button, input, a, etc.)
-- `text`: Visible text content, truncated to 100 characters
-- `placeholder`: For input fields (if present)
-- `href`: For links (if present)
-
-##### `browser_extract_content`
-
-Extract structured content from the current page using AI.
-
-```typescript
-browser_extract_content(query: string, extract_links?: boolean): string
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `query` | `string` | Yes | What to extract (e.g., "all product prices") |
-| `extract_links` | `boolean` | No | Include links in extraction (default: false) |
-
-**Returns:** Extracted content based on query
-
-**Note:** Requires `OPENAI_API_KEY` environment variable for AI extraction.
-
-#### Tab Management Tools
-
-##### `browser_list_tabs`
-
-List all open browser tabs.
-
-```typescript
-browser_list_tabs(): string
-```
-
-**Returns:** JSON array of tab information:
-```json
-[
- {
- "tab_id": 'AE21',
- "url": "https://example.com",
- "title": "Page Title"
- }
-]
-```
-
-##### `browser_switch_tab`
-
-Switch to a specific tab.
-
-```typescript
-browser_switch_tab(tab_id: string): string
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tab_id` | `string` | Yes | ID of tab to switch to (last 4 characters of TargetID) |
-
-**Returns:** Success message with tab URL
-
-##### `browser_close_tab`
-
-Close a specific tab.
-
-```typescript
-browser_close_tab(tab_id: string): string
-```
-
-**Parameters:**
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `tab_id` | `string` | Yes | ID of the Tab to close (last 4 characters of TargetID) |
-
-**Returns:** Success message with closed tab URL
-
-### Tool Response Format
-
-All tools return text content. Errors are returned as strings starting with "Error:".
-
-## Configuration
-
-### Environment Variables
-
-Configure the MCP server behavior through environment variables in Claude Desktop config:
-
-```json
-{
- "mcpServers": {
- "browser-use": {
- "command": "python",
- "args": ["-m", "browser_use.mcp.server"],
- "env": {
- "OPENAI_API_KEY": "sk-..." // For AI content extraction
- }
- }
- }
-}
-```
-
-### Browser Profile Settings
-
-The MCP server creates a browser session with these default settings:
-- **Downloads Path**: `~/Downloads/browser-use-mcp/`
-- **Wait Between Actions**: 0.5 seconds
-- **Keep Alive**: True (browser stays open between commands)
-- **Allowed Domains**: None by default (all domains allowed)
-
-## Advanced Usage
-
-### Running Standalone
-
-Test the MCP server without Claude Desktop:
-
-```bash
-# Run server (reads from stdin, writes to stdout)
-uvx 'browser-use[cli]' --mcp
-
-# The server communicates via JSON-RPC on stdio
-```
-
-### Security Considerations
-
-<Warning>
- The MCP server provides full browser control to connected AI assistants. Consider these security measures:
-</Warning>
-
-1. **Domain Restrictions**: Currently not configurable via environment variables, but the server creates sessions with no domain restrictions by default
-2. **File System Access**: The server creates a FileSystem instance at `~/.browser-use-mcp` for extraction operations
-3. **Downloads**: Files download to `~/Downloads/browser-use-mcp/`
-
-## Implementation Details
-
-### Browser Session Management
-
-- **Lazy Initialization**: Browser session is created on first browser tool use
-- **Persistent Session**: Session remains active across multiple tool calls
-- **Single Session**: Currently maintains one browser session per server instance
-
-### Tool Categories
-
-1. **Direct Browser Control**: Tools starting with `browser_` that directly interact with the browser
-2. **Agent Tasks**: Currently commented out in implementation (`browser_use_run_task`)
-
-### Error Handling
-
-- All exceptions are caught and returned as text: `"Error: {message}"`
-- Browser session initialization errors are returned to the client
-- Missing dependencies (e.g., OPENAI_API_KEY) return descriptive error messages
-
-## Troubleshooting
-
-### Server Not Appearing in Claude
-
-1. **Check configuration path:**
- - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-
-2. **Verify Python installation:**
- ```bash
- uvx 'browser-use[cli]' --version
- uvx 'browser-use[cli]' --mcp --help
- ```
-
-3. **Check Claude logs:**
- - macOS: `~/Library/Logs/Claude/mcp.log`
- - Windows: `%APPDATA%\Claude\logs\mcp.log`
-
-### Browser Not Launching
-
-```bash
-# Install Playwright browsers
-playwright install chromium
-
-# Test browser launch
-python -c "from browser_use import Browser; import asyncio; asyncio.run(Browser().start())"
-```
-
-### Connection Errors
-
-If you see "MCP server connection failed":
-
-1. Test the server directly:
- ```bash
- uvx 'browser-use[cli]' --mcp
- ```
-
-2. Check all dependencies:
- ```bash
- uv pip install "browser-use[cli]"
- ```
-
-### Content Extraction Not Working
-
-If `browser_extract_content` returns errors:
-1. Ensure `OPENAI_API_KEY` is set in the environment configuration
-2. Verify the API key is valid
-3. Check that you have credits/access to the OpenAI API
-
-## Limitations
-
-| Limitation | Description | Workaround |
-|------------|-------------|------------|
-| Single Browser Session | One browser instance per server | Restart server for new session |
-| No Domain Restrictions Config | Cannot configure allowed domains via env vars | Modify server code if needed |
-| No Agent Mode | `browser_use_run_task` is commented out | Use direct browser control tools |
-| Text-Only Responses | All responses are text strings | Parse JSON responses client-side |
-
-## Comparison with MCP Client
-
-| Feature | MCP Server (this) | [MCP Client](/customize/mcp-client) |
-|---------|-------------------|-------------------------------------|
-| **Purpose** | Expose browser to AI | Connect agent to tools |
-| **User** | Claude Desktop, etc. | Browser-use agents |
-| **Direction** | External → Browser | Agent → External |
-| **Configuration** | JSON config file | Python code |
-| **Tools** | Fixed browser tools | Dynamic from server |
-| **Use Case** | Interactive assistance | Automated workflows |
-
-## Code Examples
-
-- [Simple MCP client example](https://github.com/browser-use/browser-use/tree/main/examples/mcp/simple_server.py) - Basic MCP client connecting to browser-use server
-- [Advanced MCP client example](https://github.com/browser-use/browser-use/tree/main/examples/mcp/advanced_server.py) - Multi-server orchestration and complex workflows
-
-## See Also
-
-- [MCP Client](/customize/mcp-client) - Connect browser-use to external MCP servers
-- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification
-- [Claude Desktop](https://claude.ai/download) - Primary MCP client
diff --git a/docs/development/get-help.mdx b/docs/development/get-help.mdx
new file mode 100644
index 000000000..825af919b
--- /dev/null
+++ b/docs/development/get-help.mdx
@@ -0,0 +1,11 @@
+---
+title: "Get Help"
+description: "More than 20k developers help each other"
+icon: "circle-question"
+mode: "wide"
+---
+
+
+1. Check our [GitHub Issues](https://github.com/browser-use/browser-use/issues)
+2. Ask in our [Discord community](https://link.browser-use.com/discord)
+3. Get support for your enterprise with [email protected]
diff --git a/docs/development/observability.mdx b/docs/development/monitoring/observability.mdx
similarity index 100%
rename from docs/development/observability.mdx
rename to docs/development/monitoring/observability.mdx
diff --git a/docs/development/monitoring/telemetry.mdx b/docs/development/monitoring/telemetry.mdx
new file mode 100644
index 000000000..580e4097b
--- /dev/null
+++ b/docs/development/monitoring/telemetry.mdx
@@ -0,0 +1,31 @@
+---
+title: "Telemetry"
+description: "Understanding Browser Use's telemetry"
+icon: "chart-mixed"
+mode: "wide"
+---
+
+## Overview
+
+Browser Use is free under the MIT license. To help us continue improving the library, we collect anonymous usage data with [PostHog](https://posthog.com) . This information helps us understand how the library is used, fix bugs more quickly, and prioritize new features.
+
+
+## Opting Out
+
+You can disable telemetry by setting the environment variable:
+
+```bash .env
+ANONYMIZED_TELEMETRY=false
+```
+
+Or in your Python code:
+
+```python
+import os
+os.environ["ANONYMIZED_TELEMETRY"] = "false"
+```
+
+<Note>
+ Even when enabled, telemetry has zero impact on the library's performance. Code is available in [Telemetry
+ Service](https://github.com/browser-use/browser-use/tree/main/browser_use/telemetry).
+</Note>
diff --git a/docs/development/contribution-guide.mdx b/docs/development/setup/contribution-guide.mdx
similarity index 64%
rename from docs/development/contribution-guide.mdx
rename to docs/development/setup/contribution-guide.mdx
index cbc91ab4e..a49e8573f 100644
--- a/docs/development/contribution-guide.mdx
+++ b/docs/development/setup/contribution-guide.mdx
@@ -1,7 +1,7 @@
---
title: "Contribution Guide"
-description: "Learn how to contribute to Browser Use"
-icon: "github"
+description: ""
+icon: "handshake"
mode: "wide"
---
@@ -19,10 +19,9 @@ mode: "wide"
- Browse our [GitHub Issues](https://github.com/browser-use/browser-use/issues)
- Check out our most active issues on [Discord](https://discord.gg/zXJJHtJf3k)
- Get inspiration in [`#showcase-your-work`](https://discord.com/channels/1303749220842340412/1305549200678850642) channel
-- Explore [`awesome-browser-use-prompts`](https://github.com/browser-use/awesome-prompts)!
-## What makes a great pull request?
+## What makes a great PR?
1. Why do we need this PR?
2. Include a demo screenshot/gif
@@ -30,10 +29,9 @@ mode: "wide"
4. Keep your PR focused on a single feature
-## Contribution Process
+## How?
1. Fork the repository
-2. Create a new branch for your feature or bugfix
-3. Submit a pull request
-
-We are overwhelmed with Issues and PRs. Feel free to bump your issues/PRs with comments periodically if you need faster feedback.
+2. Create a new branch for your feature
+3. Submit a PR
+We are overwhelmed with Issues. Feel free to bump your issues/PRs with comments periodically if you need faster feedback.
diff --git a/docs/development/local-setup.mdx b/docs/development/setup/local-setup.mdx
similarity index 81%
rename from docs/development/local-setup.mdx
rename to docs/development/setup/local-setup.mdx
index bb3b4f384..a26c70448 100644
--- a/docs/development/local-setup.mdx
+++ b/docs/development/setup/local-setup.mdx
@@ -7,7 +7,6 @@ mode: "wide"
## Welcome to Browser Use Development!
-
```bash
git clone https://github.com/browser-use/browser-use
cd browser-use
@@ -48,12 +47,3 @@ For common development tasks
```bash
uv run examples/simple.py
```
-
-
-
-
-## Get help
-More than 20k developers help each other.
-1. Check our [GitHub Issues](https://github.com/browser-use/browser-use/issues)
-2. Join our [Discord community](https://link.browser-use.com/discord)
-
diff --git a/docs/development/telemetry.mdx b/docs/development/telemetry.mdx
deleted file mode 100644
index c2ef35758..000000000
--- a/docs/development/telemetry.mdx
+++ /dev/null
@@ -1,40 +0,0 @@
----
-title: "Telemetry"
-description: "Understanding Browser Use's telemetry and privacy settings"
-icon: "chart-mixed"
-mode: "wide"
----
-
-## Overview
-
-Browser Use collects anonymous usage data to help us understand how the library is being used and to improve the user experience. It also helps us fix bugs faster and prioritize feature development.
-
-## Data Collection
-
-We use [PostHog](https://posthog.com) for telemetry collection. The data is completely anonymized and contains no personally identifiable information.
-
-<Note>
- We never collect personal information, credentials, or specific content from
- your browser automation tasks.
-</Note>
-
-## Opting Out
-
-You can disable telemetry by setting an environment variable:
-
-```bash .env
-ANONYMIZED_TELEMETRY=false
-```
-
-Or in your Python code:
-
-```python
-import os
-os.environ["ANONYMIZED_TELEMETRY"] = "false"
-```
-
-<Note>
- Even when enabled, telemetry has zero impact on the library's performance or
- functionality. Code is available in [Telemetry
- Service](https://github.com/browser-use/browser-use/tree/main/browser_use/telemetry).
-</Note>
diff --git a/docs/docs.json b/docs/docs.json
index e7a146b4e..31bbee0f3 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -9,7 +9,10 @@
},
"favicon": "/favicon.ico",
"contextual": {
- "options": ["copy", "view"]
+ "options": [
+ "copy",
+ "view"
+ ]
},
"fonts": {
"family": "Geist"
@@ -42,11 +45,27 @@
},
{
"source": "/development/evaluations",
- "destination": "/development/contribution-guide"
+ "destination": "/development/setup/contribution-guide"
},
{
"source": "/cli",
"destination": "/quickstart"
+ },
+ {
+ "source": "/development/local-setup",
+ "destination": "/development/setup/local-setup"
+ },
+ {
+ "source": "/development/contribution-guide",
+ "destination": "/development/setup/contribution-guide"
+ },
+ {
+ "source": "/development/telemetry",
+ "destination": "/development/monitoring/telemetry"
+ },
+ {
+ "source": "/development/observability",
+ "destination": "/development/monitoring/observability"
}
],
"navigation": {
@@ -56,7 +75,11 @@
"groups": [
{
"group": "Get Started",
- "pages": ["introduction", "quickstart", "quickstart_llm"]
+ "pages": [
+ "introduction",
+ "quickstart",
+ "quickstart_llm"
+ ]
},
{
"group": "Customize",
@@ -112,16 +135,25 @@
{
"group": "Development",
"pages": [
- "development/contribution-guide",
- "development/local-setup",
{
- "group": "MCP",
- "icon": "link",
- "pages": ["customize/mcp-client", "customize/mcp-server"]
+ "group": "Contribution",
+ "icon": "github",
+ "isDefaultOpen": true,
+ "pages": [
+ "development/setup/local-setup",
+ "development/setup/contribution-guide"
+ ]
+ },
+ {
+ "group": "Monitoring",
+ "icon": "chart-mixed",
+ "isDefaultOpen": false,
+ "pages": [
+ "development/monitoring/observability",
+ "development/monitoring/telemetry"
+ ]
},
- "customize/hooks",
- "development/telemetry",
- "development/observability"
+ "development/get-help"
]
}
]
@@ -191,7 +223,11 @@
"display": "interactive"
},
"examples": {
- "languages": ["javascript", "curl", "python"],
+ "languages": [
+ "javascript",
+ "curl",
+ "python"
+ ],
"required": true
}
},
@@ -219,4 +255,4 @@
"linkedin": "https://linkedin.com/company/browser-use"
}
}
-}
+}
\ No newline at end of file