### Starting Server in SSE Mode Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Install dependencies and start the SSE server using uv. Clients connect to http://localhost:8000/sse. Custom paths and window sizes can be specified. ```bash # Install dependencies uv sync uv pip install playwright uv run playwright install --with-deps --no-shell chromium # Start SSE server on port 8000 uv run server --port 8000 # With custom Chrome path and larger window uv run server --port 8000 --chrome-path /usr/bin/google-chrome \ --window-width 1920 --window-height 1080 --locale fr-FR ``` -------------------------------- ### Starting Server in stdio Mode Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt For stdio transport, use the packaged CLI with mcp-proxy. Install prerequisites, build, and install the package globally, then run the server with stdio and proxy ports. ```bash # 1. Install prerequisites uv tool install mcp-proxy uv tool update-shell # 2. Build and install the package globally uv build uv tool uninstall browser-use-mcp-server 2>/dev/null || true uv tool install dist/browser_use_mcp_server-*.whl # 3. Run with stdio mode (SSE on 8000, proxy on 9000) browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000 ``` -------------------------------- ### CLI Server Command Options Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt The installed CLI entry point wraps the server's Click command and forwards all options. This example shows common options for port, stdio, chrome path, and window settings. ```bash browser-use-mcp-server run server \ --port 8000 \ --proxy-port 9000 \ --stdio \ --chrome-path /usr/bin/chromium \ --window-width 1280 \ --window-height 1100 \ --locale en-US \ --task-expiry-minutes 60 # Options: # --port INT SSE server port (default: 8000) # --proxy-port INT mcp-proxy port for stdio bridge # --stdio Enable stdio/proxy mode # --chrome-path PATH Custom Chrome/Chromium binary # --window-width INT Browser viewport width (default: 1280) # --window-height INT Browser viewport height (default: 1100) # --locale TEXT Browser locale (default: en-US) # --task-expiry-minutes INT Task TTL in minutes (default: 60) ``` -------------------------------- ### Install Prerequisites with uv Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Installs uv, mcp-proxy, and updates the shell environment. Ensure uv is installed first. ```bash curl -LsSf https://astral.sh/uv/install.sh | sh uv tool install mcp-proxy uv tool update-shell ``` -------------------------------- ### Build and Install Server for stdio Mode Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Builds a wheel distribution of the server and installs it globally as a tool. Handles potential previous uninstallations. ```bash # 1. Build and install globally uv build uv tool uninstall browser-use-mcp-server 2>/dev/null || true uv tool install dist/browser_use_mcp_server-*.whl ``` -------------------------------- ### Install Local Development Build Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Uninstalls any existing version and installs the locally built wheel file as a global tool. ```bash uv tool uninstall browser-use-mcp-server uv tool install dist/browser_use_mcp_server-*.whl ``` -------------------------------- ### Install Dependencies and Playwright Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Installs project dependencies using uv, installs Playwright, and downloads Chromium browser binaries. ```bash uv sync uv pip install playwright uv run playwright install --with-deps --no-shell chromium ``` -------------------------------- ### AI Interaction Example Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md An example of how to prompt the AI to open a URL and return specific information. ```text open https://news.ycombinator.com and return the top ranked article ``` -------------------------------- ### Set up and Proxy VNC Viewer Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Clones the noVNC repository and starts a proxy to connect to the VNC server. The default password is 'browser-use'. ```bash # Browser-based viewer git clone https://github.com/novnc/noVNC cd noVNC ./utils/novnc_proxy --vnc localhost:5900 ``` -------------------------------- ### Run Server in SSE Mode Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Starts the browser-use-mcp-server directly from source using uv, listening on port 8000 for SSE connections. ```bash uv run server --port 8000 ``` -------------------------------- ### Run Server in stdio Mode Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Runs the installed server with stdio transport, specifying ports for the server and proxy. ```bash browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000 ``` -------------------------------- ### create_mcp_server() Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Programmatically constructs and configures an MCP `Server` instance with a custom LLM and specific settings. ```APIDOC ## `create_mcp_server()` — Programmatic Server Construction Build and configure an MCP `Server` instance programmatically with a custom LLM and settings. ### Example Usage ```python from langchain_openai import ChatOpenAI from server.server import create_mcp_server # Initialize the language model llm = ChatOpenAI(model="gpt-4o", temperature=0.0) # Create configured MCP server app = create_mcp_server( llm=llm, task_expiry_minutes=30, window_width=1920, window_height=1080, locale="en-US", ) # app is a fully configured mcp.server.Server instance # It exposes: call_tool, list_tools, list_resources, read_resource handlers # app.cleanup_old_tasks is a coroutine for background task GC print(app.name) # "browser_use" ``` ``` -------------------------------- ### Configure Environment Variables Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Sets up necessary environment variables for the server. OPENAI_API_KEY is required, CHROME_PATH is optional, and PATIENT controls API call waiting. ```bash OPENAI_API_KEY=your-api-key CHROME_PATH=optional/path/to/chrome PATIENT=false ``` -------------------------------- ### Build Docker Image Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Builds a Docker image for the browser-use-mcp-server from the Dockerfile in the current directory. ```bash docker build -t browser-use-mcp-server . ``` -------------------------------- ### Programmatic MCP Server Construction with `create_mcp_server` Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Build and configure an MCP `Server` instance programmatically using `create_mcp_server` with a custom LLM and settings. The `app` instance exposes handlers for tool calls and resource management. ```python from langchain_openai import ChatOpenAI from server.server import create_mcp_server # Initialize the language model llm = ChatOpenAI(model="gpt-4o", temperature=0.0) # Create configured MCP server app = create_mcp_server( llm=llm, task_expiry_minutes=30, window_width=1920, window_height=1080, locale="en-US", ) # app is a fully configured mcp.server.Server instance # It exposes: call_tool, list_tools, list_resources, read_resource handlers # app.cleanup_old_tasks is a coroutine for background task GC print(app.name) # "browser_use" ``` -------------------------------- ### Build Wheel Distribution Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Builds a distributable wheel file for the browser-use-mcp-server package from the project root directory. ```bash # From the project root directory uv build ``` -------------------------------- ### Environment Configuration (.env file) Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Runtime settings are controlled via environment variables. Ensure OPENAI_API_KEY is set. Optional settings include CHROME_PATH, PATIENT mode, and telemetry. ```bash # .env file OPENAI_API_KEY=sk-... # Required: OpenAI API key for GPT-4o CHROME_PATH= # Optional: path to custom Chrome/Chromium binary PATIENT=false # true = block on browser_use until task completes ANONYMIZED_TELEMETRY=false # Disable telemetry # Optional tuning BROWSER_WINDOW_WIDTH=1280 BROWSER_WINDOW_HEIGHT=1100 BROWSER_LOCALE=en-US TASK_EXPIRY_MINUTES=60 ESTIMATED_TASK_SECONDS=60 CLEANUP_INTERVAL_SECONDS=3600 MAX_AGENT_STEPS=10 ``` -------------------------------- ### Build and Run Docker Image for Server Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Builds the Docker image for the browser-use-mcp-server and runs it. The server can be configured with an OpenAI API key and ports for MCP (8000) and VNC (5900). A custom VNC password can be provided via a secrets file. ```bash # Build the image docker build -t browser-use-mcp-server . # Run with default VNC password ("browser-use"), exposing MCP on 8000 and VNC on 5900 docker run --rm \ -e OPENAI_API_KEY=sk-... -p 8000:8000 \ -p 5900:5900 \ browser-use-mcp-server # Run with a custom VNC password from a secrets file echo "my-secure-password" > vnc_password.txt docker run --rm \ -e OPENAI_API_KEY=sk-... -p 8000:8000 \ -p 5900:5900 \ -v $(pwd)/vnc_password.txt:/run/secrets/vnc_password:ro \ browser-use-mcp-server # Connect a browser-based VNC viewer (noVNC) git clone https://github.com/novnc/noVNC cd noVNC ./utils/novnc_proxy --vnc localhost:5900 # Open http://localhost:6080 in a browser to watch the automation live ``` -------------------------------- ### Run Server with Environment Variable Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Runs the server with stdio transport, setting the OPENAI_API_KEY for the current session. ```bash # Set your OpenAI API key for the current session export OPENAI_API_KEY=your-api-key-here # Or provide it inline for a one-time run OPENAI_API_KEY=your-api-key-here browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000 ``` -------------------------------- ### Rebuild and Reinstall After Changes Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md After making code modifications, rebuild the wheel and reinstall the package to apply the changes. ```bash uv build uv tool uninstall browser-use-mcp-server uv tool install dist/browser_use_mcp_server-*.whl ``` -------------------------------- ### stdio Client Configuration Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md JSON configuration for a client connecting to the browser-use-mcp-server via stdio, defining the command, arguments, and environment variables. ```json { "mcpServers": { "browser-server": { "command": "browser-use-mcp-server", "args": [ "run", "server", "--port", "8000", "--stdio", "--proxy-port", "9000" ], "env": { "OPENAI_API_KEY": "your-api-key" } } } } ``` -------------------------------- ### MCP Client Configuration (stdio Mode) Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Configure MCP clients like Claude Desktop for stdio transport. Specify the command, arguments, and environment variables, including the OPENAI_API_KEY, in the client's configuration. ```json // stdio mode — Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) { "mcpServers": { "browser-server": { "command": "browser-use-mcp-server", "args": ["run", "server", "--port", "8000", "--stdio", "--proxy-port", "9000"], "env": { "OPENAI_API_KEY": "sk-..." } } } } ``` -------------------------------- ### Run Browser MCP Server with Password File Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Mounts a VNC password file as a read-only secret inside the container. Ensure `vnc_password.txt` exists in the current directory. ```bash docker run --rm -p8000:8000 -p5900:5900 \ -v $(pwd)/vnc_password.txt:/run/secrets/vnc_password:ro \ browser-use-mcp-server ``` -------------------------------- ### SSE Client Configuration Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md JSON configuration for a client connecting to the browser-use-mcp-server via SSE, specifying the server URL. ```json { "mcpServers": { "browser-use-mcp-server": { "url": "http://localhost:8000/sse" } } } ``` -------------------------------- ### MCP Client Configuration (SSE Mode) Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Configure MCP clients like Cursor, Windsurf, or others to connect to the server using SSE transport by specifying the 'url' in their configuration. ```json // SSE mode — Cursor (.cursor/mcp.json), Windsurf, or any SSE-capable client { "mcpServers": { "browser-use-mcp-server": { "url": "http://localhost:8000/sse" } } } ``` -------------------------------- ### Run Docker Container Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Runs the Docker container, mapping server and VNC ports. The container is automatically removed on exit. Uses default VNC password 'browser-use'. ```bash # Run the container with the default VNC password ("browser-use") # --rm ensures the container is automatically removed when it stops # -p 8000:8000 maps the server port # -p 5900:5900 maps the VNC port docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server ``` -------------------------------- ### Run Docker Container with Custom VNC Password Source: https://github.com/kontext-security/browser-use-mcp-server/blob/main/README.md Runs the Docker container with a custom VNC password specified in a file. ```bash # Run with a custom VNC password read from a file # Create a file (e.g., vnc_password.txt) containing only your desired password echo "your-secure-password" > vnc_password.txt # Note: The Dockerfile needs to be modified to read this file for the password. ``` -------------------------------- ### browser_use Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Submits a browser automation task. It can operate in asynchronous mode, returning a `task_id` immediately, or in patient mode (`PATIENT=true`), blocking until the task is complete and returning the full result. ```APIDOC ## MCP Tool — `browser_use` Submits a browser automation task. In default (async) mode it returns a `task_id` immediately; in patient mode (`PATIENT=true`) it blocks and returns the full result. ### Tool Call Example ```json { "name": "browser_use", "arguments": { "url": "https://news.ycombinator.com", "action": "return the title and URL of the top ranked article" } } ``` ### Async Mode Response (PATIENT=false) ```json { "task_id": "a3f1c2d4-...", "status": "pending", "message": "Browser task started. Please wait for 60 seconds, then check the result using browser_get_result or the resource URI. Always wait exactly 5 seconds between status checks.", "estimated_time": "60 seconds", "resource_uri": "resource://browser_task/a3f1c2d4-...", "sleep_command": "sleep 5", "instruction": "Use the terminal command 'sleep 5' to wait 5 seconds between status checks." } ``` ### Patient Mode Response (PATIENT=true) — returned after task completes ```json { "id": "a3f1c2d4-...", "status": "completed", "url": "https://news.ycombinator.com", "action": "return the title and URL of the top ranked article", "created_at": "2024-03-15T10:23:01.123456", "start_time": "2024-03-15T10:23:01.234567", "end_time": "2024-03-15T10:23:18.456789", "result": { "final_result": "Top article: 'Show HN: I built a...' - https://news.ycombinator.com/item?id=12345", "success": true, "has_errors": false, "errors": [], "urls_visited": ["https://news.ycombinator.com"], "actions_performed": ["navigate", "extract_content"], "extracted_content": ["Show HN: I built a..."], "steps_taken": 3 } } ``` ``` -------------------------------- ### Submit Browser Task with `browser_use` Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Use `browser_use` to submit a browser automation task. In async mode, it returns a `task_id`. In patient mode (`PATIENT=true`), it blocks and returns the full result. ```json // Tool call (sent by the MCP client / AI agent) { "name": "browser_use", "arguments": { "url": "https://news.ycombinator.com", "action": "return the title and URL of the top ranked article" } } ``` ```json // Async mode response (PATIENT=false) { "task_id": "a3f1c2d4-...", ``` ```json "status": "pending", "message": "Browser task started. Please wait for 60 seconds, then check the result using browser_get_result or the resource URI. Always wait exactly 5 seconds between status checks.", "estimated_time": "60 seconds", "resource_uri": "resource://browser_task/a3f1c2d4-...", "sleep_command": "sleep 5", "instruction": "Use the terminal command 'sleep 5' to wait 5 seconds between status checks." } ``` ```json // Patient mode response (PATIENT=true) — returned after task completes { "id": "a3f1c2d4-...", ``` ```json "status": "completed", "url": "https://news.ycombinator.com", "action": "return the title and URL of the top ranked article", "created_at": "2024-03-15T10:23:01.123456", "start_time": "2024-03-15T10:23:01.234567", "end_time": "2024-03-15T10:23:18.456789", "result": { "final_result": "Top article: 'Show HN: I built a...' - https://news.ycombinator.com/item?id=12345", "success": true, "has_errors": false, "errors": [], "urls_visited": ["https://news.ycombinator.com"], "actions_performed": ["navigate", "extract_content"], "extracted_content": ["Show HN: I built a..."], "steps_taken": 3 } } ``` -------------------------------- ### MCP Resources Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Completed and failed browser tasks are exposed as MCP resources that can be read directly via their URI, bypassing the need to call `browser_get_result`. ```APIDOC ## MCP Resources — `resource://browser_task/{task_id}` Completed and failed tasks are exposed as MCP resources. Clients can read them directly by URI without calling `browser_get_result`. ### List Resources Response (from `list_resources` handler) ```json [ { "uri": "resource://browser_task/a3f1c2d4-9e8b-4f2a-b1c3-d5e6f7a8b9c0", "title": "Browser Task Result: a3f1c2d4", "description": "Result of browser task for URL: https://news.ycombinator.com" } ] ``` ### Read Resource by URI **URI**: `resource://browser_task/a3f1c2d4-9e8b-4f2a-b1c3-d5e6f7a8b9c0` ```json { "id": "a3f1c2d4-...", "status": "completed", "url": "https://news.ycombinator.com", "result": { "final_result": "Top article: 'Show HN: ...' - https://...", "success": true, "steps_taken": 3 } } ``` ``` -------------------------------- ### Run Browser Task Asynchronously with Python Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Executes a browser automation task asynchronously, updating a task store with progress, results, and errors. This function is typically called internally by the `browser_use` MCP tool handler. Ensure the task ID is pre-initialized in `task_store` if not using the production `call_tool`. ```python import asyncio from langchain_openai import ChatOpenAI from server.server import run_browser_task_async, task_store llm = ChatOpenAI(model="gpt-4o", temperature=0.0) task_id = "my-task-001" # Pre-initialize the task entry (done automatically by call_tool in production) task_store[task_id] = { "id": task_id, "status": "pending", "url": "https://example.com", "action": "find and return the page title", "created_at": "2024-03-15T10:00:00", } async def main(): await run_browser_task_async( task_id=task_id, url="https://example.com", action="find and return the page title", llm=llm, window_width=1280, window_height=1100, locale="en-US", ) result = task_store[task_id] print(result["status"]) # "completed" or "failed" print(result["result"]["final_result"]) # "Example Domain" print(result["result"]["success"]) # True print(result["result"]["steps_taken"]) # e.g. 2 asyncio.run(main()) ``` -------------------------------- ### Create Isolated Browser Context with Python Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Creates a new, isolated Playwright browser instance and context for a single task. This prevents state leakage between tasks. Use `chrome_path=None` to utilize Playwright's managed Chromium. ```python import asyncio from server.server import create_browser_context_for_task async def example(): browser, context = await create_browser_context_for_task( chrome_path=None, # None = use Playwright's managed Chromium window_width=1280, window_height=1100, locale="en-US", ) try: # Use context for custom browser_use Agent setup print(type(browser)) # print(type(context)) # finally: await context.close() await browser.close() asyncio.run(example()) ``` -------------------------------- ### Access Browser Task Results via MCP Resources Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Completed and failed browser tasks are exposed as MCP resources. Clients can read them directly by URI without calling `browser_get_result`. ```json // List resources response (from list_resources handler) [ { "uri": "resource://browser_task/a3f1c2d4-9e8b-4f2a-b1c3-d5e6f7a8b9c0", "title": "Browser Task Result: a3f1c2d4", "description": "Result of browser task for URL: https://news.ycombinator.com" } ] ``` ```json // Read resource by URI (from read_resource handler) // URI: resource://browser_task/a3f1c2d4-9e8b-4f2a-b1c3-d5e6f7a8b9c0 { "id": "a3f1c2d4-...", ``` ```json "status": "completed", "url": "https://news.ycombinator.com", "result": { "final_result": "Top article: 'Show HN: ...' - https://...", "success": true, "steps_taken": 3 } } ``` -------------------------------- ### browser_get_result Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Polls for the result of an asynchronous browser task using the `task_id` that was returned by the `browser_use` tool. ```APIDOC ## MCP Tool — `browser_get_result` Polls for the result of an async browser task using the `task_id` returned by `browser_use`. ### Tool Call Example ```json { "name": "browser_get_result", "arguments": { "task_id": "a3f1c2d4-9e8b-4f2a-b1c3-d5e6f7a8b9c0" } } ``` ### Response When Still Running ```json { "id": "a3f1c2d4-...", "status": "running", "url": "https://news.ycombinator.com", "action": "return the top ranked article", "created_at": "2024-03-15T10:23:01.123456", "start_time": "2024-03-15T10:23:01.234567", "progress": { "current_step": 2, "total_steps": 2, "steps": [ {"step": 1, "time": "2024-03-15T10:23:03.000000", "goal": "Navigate to the URL"}, {"step": 2, "time": "2024-03-15T10:23:07.000000", "goal": "Extract top article title"} ] }, "message": "Task is running (step 2). Wait 5 seconds before checking again.", "sleep_command": "sleep 5" } ``` ### Response When Task Not Found ```json { "error": "Task not found", "task_id": "a3f1c2d4-..." } ``` ``` -------------------------------- ### Poll for Browser Task Result with `browser_get_result` Source: https://context7.com/kontext-security/browser-use-mcp-server/llms.txt Poll for the result of an async browser task using the `task_id` obtained from `browser_use`. Handles responses for running tasks, completed tasks, and task not found errors. ```json // Tool call { "name": "browser_get_result", "arguments": { "task_id": "a3f1c2d4-9e8b-4f2a-b1c3-d5e6f7a8b9c0" } } ``` ```json // Response when still running { "id": "a3f1c2d4-...", ``` ```json "status": "running", "url": "https://news.ycombinator.com", "action": "return the top ranked article", "created_at": "2024-03-15T10:23:01.123456", "start_time": "2024-03-15T10:23:01.234567", "progress": { "current_step": 2, "total_steps": 2, "steps": [ {"step": 1, "time": "2024-03-15T10:23:03.000000", "goal": "Navigate to the URL"}, {"step": 2, "time": "2024-03-15T10:23:07.000000", "goal": "Extract top article title"} ] }, "message": "Task is running (step 2). Wait 5 seconds before checking again.", "sleep_command": "sleep 5" } ``` ```json // Response when task not found { "error": "Task not found", "task_id": "a3f1c2d4-..." } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.