Core API

Browser Use Core API

Reference for the MCP tools exposed by the Browser Use plugin: the upstream Browser Use set plus ten Magus-specific additions. All are accessed via mcp__browser-use__<tool_name>. The authoritative list is whatever the server registers at runtime, so check there rather than counting this table.

1. Quick Reference Table

Editing a code editor (Monaco/CodeMirror/contenteditable)? Those expose no indexable input, so browser_type cannot reach them. Use browser_evaluate (e.g. monaco.editor.getModels()[0].setValue('...')), or browser_focus the hidden input then browser_keyboard. See §9.

2. Session Lifecycle (Critical Pattern)

Sessions are created implicitly on the first browser_navigate call. The returned session_id must be passed to every subsequent tool call. Always close sessions when done.

1. NAVIGATE (creates session) → save session_id
   mcp__browser-use__browser_navigate(url="https://example.com")
   → returns: {"session_id": "abc123", "url": "...", "title": "..."}

2. INSPECT (get DOM element map)
   mcp__browser-use__browser_get_state(session_id="abc123")
   → returns: {"selector_map": {"1": {...}, "2": {...}}, "url": "...", "title": "..."}

3. INTERACT (click, type, scroll)
   mcp__browser-use__browser_click(index=3, session_id="abc123")
   mcp__browser-use__browser_type(index=5, text="search query", session_id="abc123")

4. EXTRACT or VERIFY
   mcp__browser-use__browser_extract_content(query="product prices", session_id="abc123")
   mcp__browser-use__browser_screenshot(session_id="abc123")

5. CLOSE (ALWAYS — do not skip)
   mcp__browser-use__browser_close_session(session_id="abc123")

Rule: Every code path must close the session. If an error occurs mid-workflow, still call browser_close_session before returning.

Automatic cleanup — the browser does not wait for you

The server cleans up after itself while it runs, so a forgotten session costs disk and a stray Chrome for minutes, not for the days a Claude Code session can last:

Consequence you must plan for: cookies, localStorage and login state live in that profile directory, so they do not survive the 10-minute idle timeout. Save anything you want to keep with browser_export_session as soon as you have it — right after a login flow completes, not at the end of the workflow. A later browser_navigate starts from a clean profile and needs browser_import_session to get back in.

Nothing here is recoverable by waiting: a closed session's session_id is dead, and browser_navigate creates a new one.

3. Tool Reference (Full Schema)

3.1 browser_navigate

Navigate to a URL. Creates a new browser session if session_id is omitted.

Parameters:

Returns:

{
  "session_id": "abc123",
  "url": "https://example.com",
  "title": "Example Domain",
  "status": 200
}

When to use: First step of any browser workflow. Also used for navigating to subsequent pages within the same session.

Example:

mcp__browser-use__browser_navigate(url="https://news.ycombinator.com")
→ session_id: "hk72x1"

3.2 browser_get_state

Get the current DOM state with a numbered element map. This is the primary way to discover clickable elements, inputs, and interactive components on a page.

Parameters:

Returns:

{
  "url": "https://example.com",
  "title": "Example Domain",
  "selector_map": {
    "1": {
      "tag": "a",
      "text": "More information...",
      "href": "https://www.iana.org/domains/example",
      "attributes": {"class": "link"}
    },
    "2": {
      "tag": "input",
      "type": "text",
      "placeholder": "Search...",
      "attributes": {"id": "search", "name": "q"}
    },
    "3": {
      "tag": "button",
      "text": "Submit",
      "attributes": {"type": "submit"}
    }
  }
}

When to use: After every navigation or interaction to see the updated DOM state. Always call get_state before click or type to verify the correct element index.

⚠️ Indices are snapshot-scoped and NOT stable across calls. The same DOM element can get a different index on each get_state (the map is rebuilt every call). Never cache an index from one snapshot and reuse it later — always get_state immediately before the *_by_index call that consumes it. To avoid index churn entirely, target elements by CSS selector: browser_focus (§3.22) + browser_keyboard (§3.21), or browser_evaluate (§3.19).

3.3 browser_click

Click an element identified by its index from the selector_map.

Parameters:

*Either index OR coordinate_x/coordinate_y required.

Returns:

{"success": true, "element": "button[type=submit]", "url": "https://example.com/results"}

When to use: Clicking links, buttons, checkboxes, menu items. Prefer index over coordinates — indices are more reliable than pixel positions.

Example:

# From get_state: element 3 is the submit button
mcp__browser-use__browser_click(index=3, session_id="abc123")

3.4 browser_type

Type text into an input element identified by its index.

Parameters:

Returns:

{"success": true, "element": "input[name=q]", "typed": "search query"}

When to use: Filling text inputs, search boxes, password fields, textareas that appear in get_state's index list. Does not clear existing content — to clear first, browser_focus the field then browser_keyboard(keys=["Meta+a","Delete"]) (Control+a on Linux/Windows).

Limitation — index-only. browser_type can only target an element that has an index in get_state's selector_map. Code editors (Monaco, CodeMirror, ProseMirror, contenteditable) use a hidden/synthetic input that never appears there, so there is no index to pass. For those, use browser_evaluate (§3.19) to set the value directly, or browser_focus (§3.22) + browser_keyboard (§3.21).

Example:

# From get_state: element 2 is the search input
mcp__browser-use__browser_type(index=2, text="browser automation", session_id="abc123")

3.5 browser_extract_content

Use LLM-powered semantic extraction to find and return specific content from the page. The agent reads the page and extracts the requested information as structured text.

Parameters:

Returns:

{
  "content": "Product: Widget Pro\nPrice: $49.99\nRating: 4.5/5\nAvailability: In Stock",
  "url": "https://shop.example.com/widget-pro"
}

When to use: When you need structured data from a page but do not know the exact CSS selector. Better than get_html when the page structure is complex or varies. Costs one extra LLM inference call internally.

Avoid: On very simple pages where get_html with a known selector is faster and cheaper.

Example:

mcp__browser-use__browser_extract_content(
  query="product name, price, rating, and availability",
  session_id="abc123"
)

3.6 browser_get_html

Get raw HTML content — either the full page or scoped to a CSS selector.

Parameters:

Returns:

{
  "html": "<table class=\"data-table\"><tr><th>Name</th>...</table>",
  "selector": ".data-table",
  "url": "https://example.com/data"
}

When to use: When you need raw HTML for parsing (table data, specific DOM structure), when you know the exact CSS selector, or when LLM-based extraction is overkill. Cheaper than extract_content.

Example:

# Get just the pricing table
mcp__browser-use__browser_get_html(selector=".pricing-table", session_id="abc123")

3.7 browser_screenshot

Capture a screenshot of the current page. Returns base64-encoded PNG data.

Parameters:

Returns:

{
  "image": "<base64-encoded PNG>",
  "format": "png",
  "width": 1280,
  "height": 720,
  "url": "https://example.com"
}

When to use: Visual verification after interactions, UI debugging, before/after state comparison, documenting the browser state for users. Claude can analyze the base64 image directly.

Save to file:

# Decode base64 image to PNG file via Bash
python3 -c "import base64; open('screenshot.png','wb').write(base64.b64decode('<base64-data>'))"

3.8 browser_scroll

Scroll the page in a direction by a given amount.

Parameters:

Returns:

{"success": true, "direction": "down", "amount": 500}

When to use: Revealing lazy-loaded content, scrolling to see more elements, implementing infinite scroll pagination.

3.9 browser_go_back

Navigate back in the browser's history stack.

Parameters:

Returns:

{"success": true, "url": "https://example.com/previous-page", "title": "Previous Page"}

When to use: Returning to a list page after visiting a detail page, undoing navigation mistakes, implementing crawl-and-return patterns.

3.10 browser_list_tabs

List all open tabs in the current session.

Parameters:

Returns:

{
  "tabs": [
    {"tab_id": "tab_0", "url": "https://example.com", "title": "Example", "active": true},
    {"tab_id": "tab_1", "url": "https://github.com", "title": "GitHub", "active": false}
  ]
}

3.11 browser_switch_tab

Switch the active tab within a session.

Parameters:

Returns:

{"success": true, "tab_id": "tab_1", "url": "https://github.com", "title": "GitHub"}

3.12 browser_close_tab

Close a specific tab without closing the entire session.

Parameters:

Returns:

{"success": true, "closed_tab_id": "tab_1", "remaining_tabs": 1}

3.13 browser_list_sessions

List all currently active browser sessions. No parameters.

Returns:

{
  "sessions": [
    {"session_id": "abc123", "url": "https://example.com", "created_at": "2026-03-03T10:00:00Z"},
    {"session_id": "xyz789", "url": "https://github.com", "created_at": "2026-03-03T10:05:00Z"}
  ]
}

When to use: Before starting a workflow to detect leaked sessions from previous runs. Also for cleanup after errors.

3.14 browser_close_session

Close a browser session and release all associated resources (browser process, CDP connection, memory).

Parameters:

Returns:

{"success": true, "session_id": "abc123", "closed_at": "2026-03-03T10:10:00Z"}

Critical rule: Always close sessions. Leaked sessions consume memory and browser processes. Call in a finally-equivalent pattern: even if the workflow fails, close the session.

3.15 retry_with_browser_use_agent

Delegate a complex browser task to Browser Use's internal LLM agent. The agent autonomously navigates, clicks, types, and extracts data to complete a natural language goal.

Parameters:

Returns:

{
  "result": "Found 3 pricing plans: Starter ($9/mo), Pro ($29/mo), Enterprise (custom)",
  "steps_taken": 8,
  "final_url": "https://example.com/pricing",
  "session_id": "new_session_id"
}

When to use: Tasks where you cannot predict the exact click sequence (login flows with 2FA prompts, dynamic SPAs, complex multi-step forms). Use as escalation after direct tools fail.

When NOT to use: Simple linear workflows (navigate → extract) — direct tools are faster and more reliable.

3.16 browser_export_session

Export a live browser session's cookies and localStorage to a JSON file for later restoration.

Parameters:

Returns:

{"success": true, "path": "~/.browser-use/sessions/github.json", "cookies_count": 12}

When to use: The moment a login flow completes — not at the end of the workflow. Cookies and localStorage live in the session's Chrome profile directory, which is deleted when the browser is closed, including by the 10-minute idle timeout (see Automatic cleanup). Exporting is what makes authenticated state outlive the browser; import it in the next session to skip login.

3.17 browser_import_session

Restore a previously exported session (cookies, localStorage) into a new browser session.

Parameters:

Returns:

{"session_id": "new_id_456", "cookies_imported": 12, "url": "https://github.com/dashboard"}

3.18 browser_run_script

Run a standalone Python automation script as a subprocess.

⚠️ This does NOT run JavaScript, and does NOT share the live browser session. The subprocess gets a fresh Python interpreter that must independently have browser-use/playwright installed, and it would drive its own, separate browser — it cannot touch the page the other tools control. To run JS in the live page, use browser_evaluate (§3.19). The tool now fails fast if script_path is not a readable .py file (passing inline JS used to hang for the full timeout) and adds a hint when the subprocess hits ModuleNotFoundError. Run browser_doctor (§3.23) to see what's installed.

Parameters:

Returns:

{
  "exit_code": 0,
  "stdout": "Scraped 47 products. Saved to products.json\n",
  "stderr": ""
}

3.19 browser_evaluate

Run JavaScript in the live page the other tools are driving, and return its result. This is the in-page eval escape hatch (CDP Runtime.evaluate): read or mutate the DOM, call framework hooks, read localStorage, and drive code editors that expose no normal input (Monaco, CodeMirror). Operates on the current session — no session_id needed.

Parameters:

Returns: {"result": <value>}, or {"error": "JavaScript exception", "detail": "..."} if the JS throws.

Example — set a Monaco editor's text (the canonical use case):

mcp__browser-use__browser_evaluate(
  script="return monaco.editor.getModels()[0].setValue('graph TD; A-->B')"
)

3.20 browser_press_key

Press a single key or keyboard shortcut in the live page (CDP Input.dispatchKeyEvent, sending a keyDown+keyUp pair).

Parameters:

Returns: {"pressed": "Enter", "count": 1}

Edit shortcuts work in the real editor. Meta+/Control+ plus a/c/v/x/z/y map to the browser's selectAll/copy/paste/cut/ undo/redo commands (a synthetic modifier press alone does NOT trigger these — the CDP edit-command is attached for you). So Meta+a then Delete clears a field, and Meta+a then browser_keyboard(text=...) replaces its contents.

3.21 browser_keyboard

Send a batch of shortcuts and/or insert literal text, in order. Keys are pressed first, then text is inserted via CDP Input.insertText (the reliable way to type into a focused field or editor without needing an index).

Parameters:

Provide at least one of keys / text.

Returns: {"keys": ["Meta+a","Delete"], "text_inserted": true}

Example — clear a field and type new text:

mcp__browser-use__browser_focus(selector="textarea.inputarea")
mcp__browser-use__browser_keyboard(keys=["Meta+a"], text="new content")

3.22 browser_focus

Focus any DOM element by CSS selector — including the hidden/synthetic inputs that code editors use (e.g. Monaco's textarea.inputarea), which never appear in get_state's index list. Pair with browser_keyboard/browser_press_key.

Parameters:

Returns: {"focused": true, "selector": "..."}, or {"focused": false, "error": "No element matched ..."}.

3.23 browser_doctor

Preflight diagnosis of the plugin's environment — turns silent failures (a 300s run_script hang, ModuleNotFoundError, missing Chromium) into a one-call report. Pure inspection; never spawns a browser. Takes no arguments.

chromium_path is produced by the same resolver the launcher uses, so the doctor and the browser can never disagree. chromium_source says where it came from:

Returns:

{
  "python_version": "3.11.x",
  "python_executable": "/usr/bin/python3",
  "browser_use": {"installed": true, "version": "0.12.5"},
  "mcp": {"installed": true, "version": "..."},
  "playwright": {"installed": false, "version": null},
  "chromium_present": true,
  "chromium_path": "~/Library/Caches/ms-playwright/chromium-1234/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing",
  "chromium_source": "playwright",
  "chromium_error": null,
  "api_keys": {"ANTHROPIC_API_KEY": true, "OPENAI_API_KEY": false, "BROWSER_USE_API_KEY": false}
}

A chromium_path under /Applications/Google Chrome.app is never reported unless CHROME_EXECUTABLE_PATH asked for it: launching the user's real Chrome steals the macOS com.google.Chrome single-instance slot, so an unresolvable Chromium is reported as an error instead of quietly falling back to it. The fix is python3 -m playwright install chromium.

4. Tool Selection Guide

5. Common Errors and Fixes