Tool reference
BrowserControl exposes 69 MCP tools. Search them below, filter by category, and open any tool for its signature and parameters. Tools marked screenshot return a fresh annotated screenshot with their result; tools marked text return text only. Either kind can change browser state: clear_cookies, for example, returns text.
69 tools
find(query: str, role: str | None = None, nth: int = 1)Matches visible text and aria-label/placeholder/title/alt/value. With role (e.g. "button", "link", "textbox", "heading", "checkbox"), only elements of that role match, and query filters them by name (may be empty). Returns every match with the element ID it maps to in the new screenshot.
Full reference →Parameter Type Default Description querystrrequired Text to look for (case-insensitive substring) rolestr | NoneNoneOptional ARIA role to restrict matches to nthint1Which match to scroll to, 1-based (default 1) navigate_to(url: str)Full reference →Parameter Type Default Description urlstrrequired The URL to navigate to scroll(direction: str = 'down', amount: str = 'medium')Full reference →Parameter Type Default Description directionstr"down""up", "down", "left", or "right" amountstr"medium""small" (100px), "medium" (400px), "large" (800px), "page" (full viewport), "top", "bottom", or pixels like "500" act(steps: list[dict[str, Any]], stop_on_error: bool = True)Element IDs all refer to the screenshot taken BEFORE this call. A step whose element was removed or replaced (e.g. after navigation) fails as stale, so batch steps on the current page and navigate last. Each step is an object with "action" plus its fields: {"action": "click"|"double_click"|"right_click"|"hover", "element_id": 3} {"action": "type", "element_id": 4, "text": "hello"} {"action": "select", "element_id": 5, "option": "Canada"} {"action": "check", "element_id": 6, "checked": true} {"action": "drag", "element_id": 7, "target_id": 8} {"action": "press", "key": "Enter"} {"action": "scroll", "direction": "down", "amount": "medium"} {"action": "navigate", "url": "https://example.com"} {"action": "wait", "seconds": 1} {"action": "wait_for", "text": "Saved"} (or "selector")
Full reference →Parameter Type Default Description stepslist[dict[str, Any]]required The steps to run in order (at most 25) stop_on_errorboolTrueStop at the first failing step (default True) click(element_id: int)Full reference →Parameter Type Default Description element_idintrequired The number label shown on the element in the screenshot click_at(x: int, y: int)Full reference →Parameter Type Default Description xintrequired X coordinate yintrequired Y coordinate double_click(element_id: int)Full reference →Parameter Type Default Description element_idintrequired The number label shown on the element in the screenshot drag(source_id: int, target_id: int)Both IDs come from the same, latest screenshot.
Full reference →Parameter Type Default Description source_idintrequired The number label of the element to drag target_idintrequired The number label of the element to drop onto hover(element_id: int)Full reference →Parameter Type Default Description element_idintrequired The number label shown on the element press_key(key: str)Full reference →Parameter Type Default Description keystrrequired Key to press (e.g., "Enter", "Tab", "Escape", "ArrowDown", "Backspace"), or a combination joined with "+" (e.g., "Control+A", "Shift+Tab", "ControlOrMeta+C" for copy on any OS, "Control+Shift+T") right_click(element_id: int)Full reference →Parameter Type Default Description element_idintrequired The number label shown on the element in the screenshot scroll_to_element(element_id: int)Full reference →Parameter Type Default Description element_idintrequired The number label shown on the element type_text(element_id: int, text: str)Works on text inputs, textareas, contenteditable regions, and widgets with role=textbox/searchbox/combobox. Checkboxes, buttons, dropdowns and file inputs are refused; use check_checkbox, click, select_option or upload_file.
Full reference →Parameter Type Default Description element_idintrequired The number label shown on the element textstrrequired Text to type wait(seconds: float = 1.0)Full reference →Parameter Type Default Description secondsfloat1Time to wait in seconds (default: 1.0) handle_dialog(accept: bool = True, prompt_text: str | None = None)Call it before the action that opens the dialog. Without it, confirms and prompts are dismissed and alerts acknowledged; either way the next screenshot's text reports the dialog and how it was answered.
Full reference →Parameter Type Default Description acceptboolTrueTrue to press OK, False to press Cancel prompt_textstr | NoneNoneText to enter into a prompt() dialog (only used when accepting) wait_for(text: str | None = None, selector: str | None = None, state: str = 'visible', network_idle: bool = False, timeout_seconds: float = 10.0)Give text, a CSS selector, and/or network_idle. With none, it waits for the page to settle (load, network quiet, DOM quiet). Returns the screenshot either way and says whether the wait timed out.
Full reference →Parameter Type Default Description textstr | NoneNoneWait for an element containing this text selectorstr | NoneNoneWait for an element matching this CSS selector statestr"visible""visible" (default), "hidden", "attached", or "detached" network_idleboolFalseAlso wait until no request has been in flight for 500ms timeout_secondsfloat10Give up after this long (default 10) check_checkbox(element_id: int, check: bool = True)Idempotent: it sets the state rather than toggling. Works on inputs hidden under a styled replacement, but refuses one covered by a dialog or banner.
Full reference →Parameter Type Default Description element_idintrequired The number label of the checkbox checkboolTrueTrue to check, False to uncheck select_option(element_id: int, option: str)Full reference →Parameter Type Default Description element_idintrequired The number label of the select element optionstrrequired The value or visible text of the option to select upload_file(element_id: int, file_path: str)Full reference →Parameter Type Default Description element_idintrequired The number label of the file input file_pathstrrequired The absolute path to the file to upload get_text(element_id: int)Reads the live page, so it returns the whole text (not the truncated label from the summary). Form fields return their current value.
Full reference →Parameter Type Default Description element_idintrequired The number label of the element run_javascript(script: str)Full reference →Parameter Type Default Description scriptstrrequired JavaScript code to execute screenshot(annotate: bool = True, full_page: bool = False)Full reference →Parameter Type Default Description annotateboolTrueIf True, overlay numbered element markers (default). If False, clean screenshot. full_pageboolFalseIf True, capture the full scrollable page. extract(schema: dict[str, Any])Each value is a CSS selector, optionally with "@attr" to read an attribute ("a@href", "img@src"; href/src come back absolute). Without @attr you get the text (or a form field's value). A one-item list returns every match, and an object with "_selector" scopes its fields to that element. Example: {"title": "h1", "products": [{"_selector": ".product", "name": "h3", "price": ".price", "url": "a@href"}], "tags": [".tag"]} Selectors use the main document (not iframes or shadow DOM).
Full reference →Parameter Type Default Description schemadict[str, Any]required The fields to extract, as described above extract_links(contains: str = '', limit: int = 100)Full reference →Parameter Type Default Description containsstr""Only links whose text or URL contains this (case-insensitive) limitint100Maximum number of links to return (default 100) extract_table(element_id: int | None = None, index: int = 1, output_format: str = 'json')Full reference →Parameter Type Default Description element_idint | NoneNoneAn element inside (or containing) the table; omit to pick by index indexint1Which table on the page, 1-based, when element_id is omitted output_formatstr"json""json" (rows keyed by header), "markdown", or "csv" close_tab(index: int)Full reference →Parameter Type Default Description indexintrequired The 0-based index of the tab to close. create_tab(url: str | None = None)Full reference →Parameter Type Default Description urlstr | NoneNoneOptional URL to open in the new tab. switch_tab(index: int)Full reference →Parameter Type Default Description indexintrequired The 0-based index of the tab to switch to. close_session(name: str)Full reference →Parameter Type Default Description namestrrequired The session to close (the default session cannot be closed) connect_to_chrome(cdp_url: str = 'http://localhost:9222')The agent works in a new tab of that Chrome; list_tabs/switch_tab reach the others. Disconnecting never closes your Chrome. Isolated sessions created afterwards open as incognito-like contexts in it.
Full reference →Parameter Type Default Description cdp_urlstr"http://localhost:9222"Chrome's remote debugging endpoint (default http://localhost:9222) create_session(name: str, device: str | None = None, url: str | None = None)Use it to log in as a second user, test signed-out flows, or keep agents apart. The session is in memory only and is lost when closed.
Full reference →Parameter Type Default Description namestrrequired A name for the session, used by switch_session and close_session devicestr | NoneNoneOptional device to emulate for the whole session (see list_devices) urlstr | NoneNoneOptional URL to open in the session switch_session(name: str)Full reference →Parameter Type Default Description namestrrequired The session name (see list_sessions) get_console_logs(clear: bool = False)Full reference →Parameter Type Default Description clearboolFalseIf True, clear the captured logs after returning them get_network_requests(num_requests: int | None = None, clear: bool = False)Each line starts with a #id; pass it to get_request_details for headers and body.
Full reference →Parameter Type Default Description num_requestsint | NoneNoneNumber of recent requests to return. Defaults to 30. clearboolFalseIf True, clear the captured requests after returning them inspect_element(element_id: int)Full reference →Parameter Type Default Description element_idintrequired The number label of the element to inspect run_in_console(code: str)Full reference →Parameter Type Default Description codestrrequired JavaScript code to execute in the console set_cookie(name: str, value: str, domain: str | None = None, path: str = '/')Full reference →Parameter Type Default Description namestrrequired Cookie name valuestrrequired Cookie value domainstr | NoneNoneCookie domain (optional, defaults to current page domain) pathstr"/"Cookie path (default: "/") set_viewport(width: int, height: int)Full reference →Parameter Type Default Description widthintrequired Width in pixels heightintrequired Height in pixels clear_mocks(url_pattern: str | None = None)Full reference →Parameter Type Default Description url_patternstr | NoneNoneThe pattern given to mock_route; omit to remove every mock export_har(name: str = '', include_bodies: bool = False)Open it in Chrome DevTools (Network > Import) or any HAR viewer.
Full reference →Parameter Type Default Description namestr""File name without extension (default: timestamp) include_bodiesboolFalseAlso save response bodies (up to 1MB each) get_request_details(request_id: int, include_body: bool = True)Full reference →Parameter Type Default Description request_idintrequired The #id shown by get_network_requests or wait_for_response include_bodyboolTrueInclude the response body (text, truncated; binary as base64) mock_route(url_pattern: str, status: int = 200, body: str = '', content_type: str = 'application/json', headers: dict[str, str] | None = None, abort: bool = False)Use it to test error states (status=500), stub an API, or block trackers (abort=True). Replaces any earlier mock with the same pattern.
Full reference →Parameter Type Default Description url_patternstrrequired Substring of the URL, a glob like "**/api/users*", or "re:<regex>" statusint200HTTP status to return (default 200) bodystr""Response body (e.g. a JSON string) content_typestr"application/json"Content-Type of the body (default application/json) headersdict[str, str] | NoneNoneExtra response headers abortboolFalseFail matching requests with a network error instead of responding wait_for_response(url_pattern: str, status: int | None = None, timeout_seconds: float = 10.0)Responses that arrived during the previous tool call count, so call this right after the action that sends the request.
Full reference →Parameter Type Default Description url_patternstrrequired Substring of the URL, a glob like "**/api/save*", or "re:<regex>" statusint | NoneNoneOnly accept this HTTP status timeout_secondsfloat10Give up after this long (default 10) emulate_device(name: str)Pass "none" to go back to the desktop viewport. Pixel ratio and the mobile layout viewport need a new context: use create_session(name, device) for a fully faithful device.
Full reference →Parameter Type Default Description namestrrequired A device from list_devices(), e.g. "iPhone 13" or "Pixel 7" list_devices(contains: str = '')Full reference →Parameter Type Default Description containsstr""Only names containing this (case-insensitive), e.g. "iphone" set_color_scheme(scheme: str = 'dark')Full reference →Parameter Type Default Description schemestr"dark""dark", "light", or "no-preference" set_geolocation(latitude: float, longitude: float, accuracy: float = 10.0)Full reference →Parameter Type Default Description latitudefloatrequired Latitude in degrees, e.g. 51.5074 longitudefloatrequired Longitude in degrees, e.g. -0.1278 accuracyfloat10Accuracy radius in meters (default 10) set_timezone(timezone_id: str)Full reference →Parameter Type Default Description timezone_idstrrequired IANA name such as "America/New_York" or "Asia/Tokyo"; "" resets throttle_network(profile: str = 'slow-3g')Full reference →Parameter Type Default Description profilestr"slow-3g""slow-3g", "fast-3g", "4g", "offline", or "none" to remove throttling export_test(name: str = '', language: str = 'python', clear: bool = False)Covers navigation, clicks, typing, keys, selects, checkboxes, uploads, drags, scrolls, waits for text, dialog answers, and request mocks, since the session started or since start_recording(). Elements are located by test id, role and name, label, placeholder, text, or CSS, never by SoM IDs. Typed passwords become environment variables. Review before committing.
Full reference →Parameter Type Default Description namestr""Test name and file name (default: timestamp) languagestr"python""python" (pytest-playwright) or "typescript" (@playwright/test) clearboolFalseEmpty the action log afterwards, to start the next test fresh start_recording(name: str = '')Full reference →Parameter Type Default Description namestr""Optional name for the recording (default: timestamp) take_snapshot(name: str = '')Full reference →Parameter Type Default Description namestr""Optional name for the snapshot (default: timestamp)
By category
find.Interaction →Click, type, keys, hover, drag, and act.Waiting & dialogs →Wait for conditions; dialogs and downloads.Forms →Dropdowns, checkboxes, and file uploads.Content →Markdown, element text, JavaScript, screenshots.Extraction →Tables, links, and schema fields as JSON.Tabs →Open, switch, list, and close tabs.Sessions →Your own Chrome and isolated sessions.DevTools →Console, errors, requests, cookies, inspection.Network →Mocks, response waits, request details, HAR.Emulation →Devices, color scheme, timezone, location, throttling.Recording →Traces, snapshots, and test export.Also in the reference
- MCP resources: captured data readable without a tool call.
- Configuration: environment variables and command-line flags.
tools.json: this catalog as JSON, generated from the server.
