Launch a new browser session.

Purpose

Creates a Selenium WebDriver instance and registers it in the MCP session store. The returned session_id must be passed to all subsequent browser tool calls.

Typical Agent Workflow

1. open_browser

2. open_url

3. wait_for_page

4. interact with elements

Parameters

browser : str Browser type to launch (default: "chrome"). headless : bool Run without a visible window (default: False). Set True on servers, Docker containers, or CI environments.

Returns

dict {"session_id": str, "browser": str, "headless": bool, "status": str, "message": str}

Note

Only call this tool ONCE per workflow, unless explicitly instructed. Do not call it again unless the previous browser session was closed.

Close the browser session and free its resources.

Parameters

session_id : str Active browser session identifier.

Maximize the browser window.

Parameters

session_id : str Active browser session identifier.

Switch the browser to fullscreen mode.

Parameters

session_id : str Active browser session identifier.

Navigate the browser to a specific URL.

Parameters

session_id : str Active browser session identifier. url : str Full URL to open (must include scheme, e.g. https://).

Navigate back one step in browser history.

Parameters

session_id : str Active browser session identifier.

Navigate forward in browser history.

Parameters

session_id : str Active browser session identifier.

Reload the current web page.

Parameters

session_id : str Active browser session identifier.

Wait until the page body element is present in the DOM.

Purpose

Call after open_url or any navigation to give the page time to load before attempting interactions.

Parameters

session_id : str Active browser session identifier. timeout : int Maximum seconds to wait (default: 10).

Returns

dict { "session_id": str, "timeout_set": timeout that was passed as a parameter, "status": str, "message": str }

Retrieve all open browser tabs for the current session.

Purpose

Provides visibility into all tabs so the agent can decide which tab to switch to.

Each tab is identified by an index and optional name.

Parameters

session_id : str Active browser session identifier.

Returns

dict { "session_id": str, "status": str, "message": str, "tabs": [ { "index": int, "name": str, "current": bool } ] }

Retrieve the currently active browser tab.

Purpose

Allows the agent to confirm which tab is currently active without listing all tabs.

Parameters

session_id : str Active browser session identifier.

Returns

dict { "session_id": str, "status": str, "message": str, "tab": { "index": int, "name": str, "current": bool } }

Switch to a specific browser tab using its index.

Purpose

Allows the agent to move between multiple open tabs in the same browser session.

Always call get_tabs first to understand available tab indexes.

Parameters

session_id : str Active browser session identifier. index : int Index of the tab to switch to.

Returns

dict { "session_id": str, "status": str, "message": str }

Open a new browser tab and optionally navigate to a URL.

Purpose

Creates a new tab within the current browser session. The newly opened tab becomes the active tab.

Parameters

session_id : str Active browser session identifier. url : str, optional URL to open in the new tab. If not provided, a blank tab is opened.

Returns

dict { "session_id": str, "status": str, "message": str }

Close a specific browser tab using its index.

Purpose

Allows the agent to close tabs that are no longer needed. After closing, focus automatically shifts to a valid remaining tab.

Parameters

session_id : str Active browser session identifier. index : int Index of the tab to close.

Returns

dict { "session_id": str, "status": str, "message": str }

Assign a custom name to a browser tab.

Purpose

Helps the agent label tabs meaningfully for easier navigation across multiple tabs.

Parameters

session_id : str Active browser session identifier. index : int Index of the tab to name. name : str Custom name to assign to the tab.

Returns

dict { "session_id": str, "status": str, "message": str }

Click an interactive element on the current webpage using its index.

Purpose

This tool allows the agent to click buttons, links, or other interactive UI elements on the page. The element must first be discovered using get_interactive_elements, which returns a list of visible elements and assigns each one an index.

The index returned by get_interactive_elements must be used with this tool to select the correct element.

Recommended Agent Workflow

1. Navigate to the desired page using open_url.

2. Wait for the page to load using wait_for_page.

3. Call get_interactive_elements to discover clickable elements.

4. Review the returned elements and identify the correct one.

5. Call click_element using the element's index.

6. If navigation occurs after clicking, call wait_for_page again.

Parameters

session_id : str Active browser session identifier returned by open_browser.

index : int Index of the element to click. This index must correspond to an element returned by get_interactive_elements.

Returns

dict { "session_id": str "index": index of the element that was clicked, "status": str "message": str }

Error Conditions

• If get_interactive_elements has not been called yet, the element cache will be empty and the tool will return an error.

• If the provided index does not exist in the cached elements list, the tool will return an "Invalid element index" error.

Notes

The tool automatically scrolls the element into view before clicking to ensure it is visible and interactable.

Enter text into an input field or textarea using an element index.

Purpose

This tool allows the agent to type text into editable elements such as input fields or textareas. The element must first be discovered using get_interactive_elements, which returns a list of visible UI elements along with their corresponding indexes.

The index returned by get_interactive_elements should be used directly with this tool to identify which element to type into.

Recommended Agent Workflow

1. Call get_interactive_elements to retrieve all interactive elements.

2. Identify the correct element by reviewing fields such as:

   • text

   • placeholder

   • aria_label

   • tag

3. Use the provided index to call type_into_element.

4. If the page changes after typing (e.g., search suggestions appear), consider calling get_interactive_elements again.

Parameters

session_id : str Active browser session identifier returned by open_browser.

index : int Index of the element to type into. This must correspond to the index returned by get_interactive_elements.

text : str The text to be entered into the selected element.

Returns

dict { "session_id": str, "index": index of the element used, "text_to_type": the text to enter, "status": str, "message": str }

Error Conditions

If get_interactive_elements has not been called previously, the element cache may be empty and the tool will return an error.

Notes

This tool automatically clears any existing text in the element before entering the new text.

Retrieve visible interactive elements from the current web page.

Purpose

This tool scans the page for interactive elements using a performance-optimized selector that works across modern web applications (React, Angular, dynamic UIs).

It identifies elements based on interaction signals such as: - semantic HTML tags (button, input, link) - ARIA roles (button, link, tab, option) - click handlers (onclick) - focusable elements (tabindex)

The discovered elements are returned with an assigned index. This index must be used when interacting with elements using tools such as: - click_element - type_into_element

The function also stores the discovered Selenium elements in an internal session cache so that subsequent tools can safely interact with the exact same elements without re-querying the DOM.

Recommended Agent Workflow

1. Navigate to a webpage using open_url.

2. Wait for the page to fully load using wait_for_page.

3. Call get_interactive_elements to discover UI elements.

4. Review the returned list of elements and identify the correct element.

5. Use the provided index with tools like:

   • click_element(index)

   • type_into_element(index, text)

Parameters

session_id : str Active browser session identifier.

Returns

dict { "session_id": str, "count": int, "elements": [ { "index": int, "role": str, "label": str } ], "status": str, "message": str }

Notes

• The returned index is required for all interaction tools.

• Only visible and meaningful elements are returned to reduce noise.

• This tool is optimized for speed and avoids scanning the entire DOM.

Retrieve a simplified accessibility tree of the current page.

Purpose

Returns interactive elements with semantic roles so AI agents can understand UI meaning (buttons, links, inputs, dropdowns). Returned index values map directly to click_element.

Parameters

session_id : str Active browser session identifier.

Returns

dict { "session_id": str, "count": int, "nodes": [{"index": int, "role": str, "name": str, "tag": str, "id": str, "name_attr": str, "placeholder": str, "aria_label": str}], "status": str, "message": str }

Retrieve the title of the current web page.

Parameters

session_id : str Active browser session identifier.

Returns

dict { "session_id: str, "page_title": str (title of the page), "status": str, "message": str }

Retrieve visible text from the page body.

Purpose

Provides page text for reasoning, validation, or extraction. Text is truncated to max_chars characters; check the returned truncated flag to know whether content was cut.

Parameters

session_id : str Active browser session identifier. max_chars : int Maximum characters to return (default: 5000).

Returns

dict { "session_id": str, "page_text": str (Page text extract), truncated": bool (True, if the page_text is truncated. Else, False), "total_chars": int, "status": str, "message": str }

Capture a screenshot of the current browser window.

Purpose

Useful for debugging, failure reporting, or visual analysis. Screenshots are saved to the directory set by the MCP_SCREENSHOT_DIR environment variable (default: system temp dir).

Parameters

session_id : str Active browser session identifier.

Returns

dict { "session_id": str, screenshot_path: str, "status": str, "message": str }