selenium-mcp

Set a cookie in the browser, e.g. a session or feature-flag cookie to skip a login screen or switch on a test mode. Browsers only accept cookies for the site that is currently open, so navigate to a page on that domain first. The page does not see the cookie until its next request, so refresh (history) or navigate afterwards. Setting an existing name replaces that cookie.

Handle a native browser dialog opened by alert(), confirm(), or prompt(). While one is open, other page actions fail until it is handled. get_text reads the message; accept clicks OK and dismiss clicks Cancel, which close the dialog and let the page act on the answer (this cannot be undone); send_text types into a prompt() before you accept it. Every action returns the dialog's text. Fails if no dialog is open. Custom in-page modals are not native dialogs: use click on their buttons instead.

Test step: check that an element's attribute or property equals (default), contains, or matches a regular expression, e.g. that a button is disabled or an input's value is 'standard_user'. Waits for the element to exist; a missing attribute counts as an empty string. Fails as a tool error showing expected vs actual.

Test step: check that an element's visible text equals, contains (default), or matches a regular expression. Waits for the element to be visible, then checks once (it does not wait for the text to change). Passes with the actual text, or fails as a tool error showing expected vs actual, so it works as an acceptance check. Use get_text to just read text without a pass/fail.

Test step: check that an element becomes visible within timeoutMs, e.g. a success banner or a cart badge. Passes as soon as it is displayed; fails as a tool error if it is missing or stays hidden. Similar to wait_for_element with visible: true, but phrased as a pass/fail assertion.

Run up to 10 steps in one call. Supported actions: navigate, wait_for_element, wait_for_page, click, type, select_option, and execute_script, each with the same fields as the standalone tool (selectors only, not capture_page refs). Use it for known linear flows such as a login or form fill, to save round trips. By default it stops at the first failing step; the result lists every executed step with its details or error.

Snapshot the page's visible interactive elements and headings (links, buttons, inputs, selects, textareas, ARIA roles, h1-h4) with stable refs e1, e2, ... and a reusable selector for each. Pass a ref to click, type, get_text, select_option, interact, or scroll instead of guessing a selector. Refs belong to this snapshot, so capture again after navigation or major page changes. Prefer this over screenshots or get_page_source to understand what is on the page.

Click an element: waits until it is visible and enabled, then clicks it (scrolling it into view). Target it by selector or by a ref from capture_page. If clicks fail intermittently because of overlays, animations, or re-rendering, use retry_click; for double-click, right-click, or hover, use interact. Fails with the reason if the element does not become clickable within timeoutMs.

Delete one cookie by name, or every cookie for the current page when name is omitted. Deleting all cookies usually logs the user out and resets consent banners and preferences; it cannot be undone. The page notices on its next request, so refresh (history) or navigate afterwards.

Run synchronous JavaScript in the current page and return its result (use a return statement); arguments are available as arguments[0], arguments[1], .... Useful for reading several values in one call, or page state no other tool exposes (localStorage, computed styles, element counts). The script runs with the page's privileges and can change the page; for user actions such as clicking and typing, prefer click and type so real events fire.

Look up one element and describe it: tag, visible text, and whether it is displayed and enabled. Waits for it to exist. Use it to confirm a selector matches the intended element, or to inspect an element before acting. To discover elements without knowing a selector, use capture_page; to wait for something to appear, use wait_for_element.

Move into or out of an iframe. Elements inside an iframe (embedded widgets, rich-text editors, payment fields) cannot be found by other tools until you switch into it. switch = enter a frame by selector, index, or nameOrId; parent = go up one level; default = return to the main page. The switch lasts until you change it again or a new page loads, so switch back with default when you are done inside the frame.

Read an attribute or property of an element, e.g. an input's value, a link's href, or whether it is disabled, checked, or aria-expanded. Waits for the element to exist (it does not need to be visible). Returns the value, or null if it is not set; the live property wins when one exists, so 'value' gives the text currently in an input. Use get_text for visible text, and assert_attribute to check a value as a test step.

Read the cookies the browser holds for the current page: all of them, or one by name. Includes httpOnly cookies that page JavaScript cannot see. Returns each cookie's name, value, domain, path, expiry, and flags. Useful to check that a login created a session cookie, or to copy one into another session with add_cookie.

Return the URL of the current tab, including any query string and fragment. Use it to confirm where a click or redirect landed; to wait until the URL changes, use wait_for_page.

Return the page's current HTML (the live DOM, including changes made by scripts), cut off at maxLength characters. Returns the HTML, its full length, and whether it was truncated. It is large and noisy: to find elements to act on, prefer capture_page; to read specific text or values, use get_text or get_attribute. Use this for raw markup such as meta tags, hidden fields, or inline data.

Read the visible text of an element: what a user sees, not hidden text or an input's value. Waits for the element to be visible, then returns its text (trimmed by default). Target it by selector or by a ref from capture_page. To read an input's value or any attribute, use get_attribute; to check text as a pass/fail test step, use assert_text.

Return the current page's title, the text shown in the browser tab. Use it to confirm which page is open; to wait until the title changes, use wait_for_page with titleContains.

Browser history navigation: go back to the previous page (like the Back button), go forward to the next page, or refresh/reload the current page (like F5). Waits for the page to load and returns the new URL and title. To open a specific URL, use navigate instead. Element refs from an earlier capture_page may be stale afterwards, so capture the page again before using refs. Refresh can reset unsaved form input.

Mouse actions beyond a plain click: double_click, right_click (opens a context menu), hover (reveals menus and tooltips), or click performed as a real mouse move-and-click. Waits for the element to be visible (hover) or visible and enabled (clicks). Target it by selector or by a ref from capture_page. For an ordinary click, prefer click.

Open a URL in the current tab and wait for the page to load (up to the pageLoadTimeoutMs set in start_browser). Returns the final URL after any redirects, and the page title. Use history to go back, forward, or refresh; use wait_for_page when a later redirect or client-side route change still has to happen.

Press one key on whichever element currently has focus, e.g. Enter to submit, Tab to move focus, Escape to close a dialog, or arrow keys in a list. Named keys: enter, tab, escape/esc, backspace, delete, space, arrowup, arrowdown, arrowleft, arrowright, home, end, pageup, pagedown; any other value is typed as literal text. To type into a specific field, use type, which focuses the field first.

Click with retries, for clicks that fail intermittently: the element is covered by a loading overlay or animation, or re-rendered (stale) between being found and clicked. Each attempt waits for the element to be visible and enabled, then clicks; failed attempts pause delayMs before the next. Returns the attempt that succeeded, or every attempt's error. Try click first; use this when click failed because of timing.

Scroll the page: scroll down or up by pixels, jump to the top or bottom, or scroll an element into view (to the middle of the screen). Also scrolls inside a scrollable container (chat panels, tables, sidebars with their own scrollbar) when you pass that container as selector/ref together with to or deltaX/deltaY. Returns the scroll position with atTop/atBottom flags. For lazy-loaded or infinite-scroll pages ('load more' on scroll), scroll to the bottom, wait_for_element for the new items, and repeat until atBottom stays true and nothing new appears. click and type already scroll their target into view, so use this to reveal content or trigger lazy loading.

Select an option in a native <select> dropdown by visible text, value, or zero-based index, and return the resulting selection. Waits for the dropdown to be visible, then clicks the option like a user so change events fire; on a multi-select it adds to the current selection. If nothing matches, the error lists the available options so you can retry. Only for real <select> elements; for custom dropdowns built from other elements, click the trigger and then the option.

Permanently remove a saved selector hint from the hints file, e.g. when the site changed and the selector no longer works. This cannot be undone; save a corrected hint with selector_hint_save. Fails if no hint with that key exists for the domain.

Look up a saved selector by key for a site and return it, ready to pass as the selector of click, type, get_text, and similar tools. Fails if no hint with that key exists for the domain; use selector_hint_list to see what is saved.

List saved selector hints (key, domain, and selector) for every site, or only for one domain. Check this at the start of a run on a familiar site to reuse known selectors. Does not need a browser to be running.

Remember a selector that worked, under a short key for a site, so later runs can reuse it instead of rediscovering the element. Hints are saved to a JSON file on disk (.selenium-mcp/selector-hints.json in the server's working directory, or SELENIUM_MCP_SELECTOR_HINTS_PATH) and survive restarts. Save a hint after a selector has worked, e.g. after a successful click. Returns the saved hint.

Open an additional, independent browser session (its own window, cookies, and login state) and make it the active one; all other tools act on the active session. Use it to test several users at once, such as a buyer and a seller, or to compare two states side by side. Switch between sessions with session_select. Takes the same options as start_browser. Returns the new session and overall status.

Close one browser session by id and quit its browser; its cookies, login state, and open pages are lost. If it was the active session, another open session becomes active, or none if it was the last. To close just the active session, stop_browser does the same.

List every open browser session (id, browser, headless, window size, start time) and which one is active. Use it to find session ids for session_select or session_destroy, or to check what is still running.

Make an existing browser session the active one, so every following tool call acts on that browser. The other sessions stay open exactly as they were. Use session_list to see the available ids.

Start a browser session (Chrome, Firefox, or Edge) that all other tools act on. Call this first. Only one session can be started this way: call stop_browser before starting another, or use session_create to run several browsers at once. The matching driver is downloaded automatically by Selenium Manager. Returns the session status.

Close the active browser session and quit its browser; its cookies, login state, and open pages are lost. With several sessions open, only the active one closes and another becomes active; use session_destroy to close a specific one. Safe to call when nothing is running. Call it when you are done, so no browser is left open.

Capture a PNG screenshot of the visible viewport. Returns it as base64 and/or saves it to savePath (folders are created as needed; an existing file is overwritten). Use it when visual layout or appearance matters, or to show the user a step. To check text or state, prefer capture_page, get_text, or the assert tools: they are exact and much smaller than an image.

Type text into an input, textarea, or other editable element. Waits for it to be visible, clears the current value first (clearFirst: false appends instead), then sends the text as keystrokes so the page's input events fire; submit: true presses Enter afterwards. Target it by selector or by a ref from capture_page. For dropdowns use select_option; for single keys like Tab or Escape use press_key.

Attach a local file to a file input (<input type="file">) without opening the operating system's file picker. Waits for the input to exist; it may be hidden, as styled upload buttons often hide the real input, so target the input itself. The file must exist on the machine running this server. After attaching, click the page's upload or submit button if it has one.

Wait for an element to exist in the page, or with visible: true to also be displayed, then return its tag and state (displayed, enabled). Use it before acting on content that loads later: spinners finishing, lazy lists, dialogs, single-page-app transitions. click, type, and get_text already wait for their own target, so use this to wait for something else first. For URL or title changes, use wait_for_page.

Wait until the current page's URL or title meets a condition: URL contains text, URL matches a regular expression, and/or title contains text (all given conditions must hold). Use after an action that navigates or redirects (submitting a login form, clicking a link, a single-page-app route change) before checking the new page. Returns the final URL and title; on timeout, the error shows the URL and title the page actually had. To wait for an element to appear, use wait_for_element instead.

Manage browser tabs and windows, and resize the viewport. list = all window handles plus the current one; switch = go to a handle from list; switch_latest = go to the newest tab/window (e.g. after a link opened a new tab); new_tab / new_window = open a blank one and switch to it; close = close the current one (then switch to another handle). resize = set the viewport (page area) to width x height for responsive or mobile testing, e.g. 390x844 phone, 768x1024 tablet, 1920x1080 desktop (exact phone sizes use device emulation on Chrome/Edge); maximize = maximize the window. Returns window handles, or the resulting window and viewport sizes.