# browser-mcp [Health: Active] **Category:** 📂 Browser Automation **Repository:** https://github.com/Agent360dk/browser-mcp **GitHub Stars:** 62 **Views:** 13 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/browser-mcp ## Description Control your real Chrome from Claude Code. 29 tools with CAPTCHA solving and multi-session. ## Tools Capabilities this server exposes over MCP: - **browser_navigate** — Navigate the active browser tab to a URL. Reuses the current tab by default (no tab spam). Pass new_tab=true only when you need to keep the current page open. In the current tab the answer is ok:true only when Chrome took the address and the new page is proven loaded within about 25 s (the wait ends half a second before that limit). If the page asks "Leave site?", the default answer is Stay (an armed browser_handle_dialog answers instead) and the reply is error beforeunload-blocked with the tab's actual url: the page may hold unsaved work, so ask the user (browser_ask_user) before you call again with leave_page:true. Other errors, each with sent (was the address sent to Chrome?) and a note on what to do: navigation-in-progress (another navigate is working in this tab, or - with op_id null - an earlier answer to a dialog on the tab is not confirmed yet; wait a moment), dialog-open (a dialog is on screen - answer it with browser_handle_dialog), tab-not-responding (busy page, or a dialog Chrome does not show us), navigation-failed, dialog-unconfirmed, navigation-unconfirmed (no load proven in time; may_complete_later and pending_url say it can still happen - read the tab before sending it again; a download or a 204 answer never loads a page and ends here too), tab-closed (Chrome no longer has the tab), session-changed (another call changed the session's active tab while this one waited; nothing was sent). - **browser_get_page_content** — Get the content of the current page as text or HTML. Pass `selector` to read one part of a large page instead of all of it - on a big logged-in app the full HTML can run past a million characters. The answer is capped at 30000 characters by default and says so when it had to cut, with the real length, so a truncated page is never mistaken for a whole one. - **browser_extract_list** — Read the rows of a long or virtualised list by scrolling its container until no new rows appear. Use this instead of browser_get_page_content whenever a page shows a repeating list longer than the viewport - mail lists (Outlook, Gmail), invoice/billing tables, search results, transaction histories. Those UIs keep only ~7 rows in the DOM at a time, so a single page read returns a sliver and looks complete. Pass the CSS selector of one repeating row (e.g. '[role="option"]', 'tr', '[role="listitem"]'); the scrollable ancestor is found automatically. When the tab is the active one in its window, it scrolls with real wheel events, also at the bottom, so a feed that loads more rows on wheel (Threads, X) loads them. A hidden page (a background tab) gets no wheel or scroll events, IntersectionObserver callbacks or animation frames, so a list that loads or renders rows while you scroll stops at what is already there; then reached_end is false and `note` says why. Returns deduplicated row text, scroll_method (wheel or script) and reached_end, which is true only when the list stood at its bottom in a visible page with no new rows, growth or movement for stable_rounds rounds in a row. If the selector matches no rows with text, the answer is error "no-rows". - **browser_screenshot** — Take a screenshot of the visible area of the current tab. Returns base64 PNG, or saves to disk if path is provided. The image is in device pixels; when Chrome reports them in time, the answer also gives the CSS viewport size and devicePixelRatio, which browser_click_xy coordinates need. Chrome stays where it is: if its window is covered by other windows, there is no picture and the answer is error "window-covered". - **browser_execute_script** — Execute JavaScript in the current page. IMPORTANT: the parameter is `code` (NOT `script` - though that alias is accepted), and it must be an EXPRESSION, not statements: use an IIFE `(() => { ...; return x; })()`. Top-level `return` is a syntax error (the handler wraps code in parentheses). - **browser_double_click** — True double-click on an element (two trusted press/release pairs with escalating clickCount). Use for open-item actions (calendar events, file lists) where two single clicks would trigger inline-rename instead (e.g. OWA month view). If the mouse would not reach the target at its center - another element lies in front of it (an overlay, a dialog's backdrop), the target does not take clicks there (pointer-events, visibility, clipping), or a different control inside it would get the click (a delete button on a card; for a container that is not clickable itself, its own plain link with a real address (a hash route with a path, such as #/orders, counts; a fragment with no target on the page does not) does not count, nor does a web component's own button that covers it, nor a box with a checkbox, switch or radio role right next to a hidden field and the only one in the nearest label around it, a label of that field (a box inside a closed shadow root cannot be seen and is not counted), which counts as that field) - the answer is ok:false with error "covered" and covered_by. Found before the mouse is sent, nothing is sent; if it comes in front afterwards, the rest of the presses and clicks are stopped (a release the page moves elsewhere is let through), and the answer also has maybe_landed: true, because the page may already have reacted. - **browser_right_click** — Right-click an element (trusted CDP mouse events) to open page-level context menus (web apps like OWA/Google Docs render their own). Note: Chrome's NATIVE context menu does not open via CDP - only in-page menus. If the mouse would not reach the target at its center - another element lies in front of it (an overlay, a dialog's backdrop), or the target does not take clicks there (pointer-events, visibility, clipping) - the answer is ok:false with error "covered" and covered_by. Found before the mouse is sent, nothing is sent; if it comes in front afterwards, the rest of the presses and clicks are stopped (a release the page moves elsewhere is let through), and the answer also has maybe_landed: true, because the page may already have reacted. - **browser_click_xy** — ESCAPE HATCH: Click at raw viewport coordinates (CSS pixels) with fully trusted mouse events. Use when a visible button resists every selector strategy (Azure portal dialogs, Knockout-bound divs, canvas UIs): take a screenshot, read the button's position, click its center. Coordinates are CSS pixels, NOT image pixels: convert with the viewport line browser_screenshot returns: x_css = x / W * css_width and y_css = y / W * css_width, where (x, y) is the point in the image and W is the width the image is shown to you at. - **browser_reattach_debugger** — RECOVERY: Force-detach and re-attach the Chrome debugger on the current tab. Use when interactive tools (click/fill/press_key) start timing out or reporting ghost-attach ("Debugger attach failed ... ghost") while list_tabs still works - faster than reloading the extension. - **browser_click** — Click an element on the page. Supports CSS selectors AND text-based selectors. Auto-scrolls element into view. Uses real mouse events (works on Angular/React SPAs and CSP-strict sites like Google, Stripe). A text selector looks inside an open modal dialog first (a opened with showModal, or a visible element with aria-modal="true"), exact text before partial. If the mouse would not reach the target at its center - another element lies in front of it (an overlay, a dialog's backdrop), the target does not take clicks there (pointer-events, visibility, clipping), or a different control inside it would get the click (a delete button on a card; for a container that is not clickable itself, its own plain link with a real address (a hash route with a path, such as #/orders, counts; a fragment with no target on the page does not) does not count, nor does a web component's own button that covers it, nor a box with a checkbox, switch or radio role right next to a hidden field and the only one in the nearest label around it, a label of that field (a box inside a closed shadow root cannot be seen and is not counted), which counts as that field) - the answer is ok:false with error "covered" and covered_by. Found before the mouse is sent, nothing is sent; if it comes in front afterwards, the rest of the presses and clicks are stopped (a release the page moves elsewhere is let through), and the answer also has maybe_landed: true, because the page may already have reacted. Examples: "button:text(Get started)", "text=Submit", "#my-button", "a.btn-primary" - **browser_fill** — Fill a form input field with a value. Supports CSS selectors AND text-based selectors. Auto-scrolls and focuses the element. Works on CSP-strict sites via Chrome Debugger API. For date inputs use browser_set_date, for autocomplete/combobox use browser_set_combobox. With a text selector the field is clicked first, so the same check as browser_click applies: if the mouse would not reach it at its center, nothing is typed and the answer is ok:false with error "covered". - **browser_press_key** — Press a keyboard key (Enter, Tab, Escape, ArrowDown, etc.). Useful for submitting forms, navigating dropdowns, closing dialogs. Supports modifier keys (ctrl, alt, shift, meta). While ctrl, meta or alt is held, no character is typed. With ctrl or meta (and no shift), the letters a, c, x, v, z and y are sent with Chrome's own editing command - select all, copy, cut, paste, undo, redo; z with shift is redo - including on macOS, where Chrome runs no shortcut for a synthetic key without it. The answer names the command that was sent in `shortcut`; `landed` says the page received the key, not what the command did. Paste inserts the user's real clipboard into the page, and copy and cut replace what is on it. - **browser_scroll** — Scroll the page to an element or by pixel amount. Useful for reaching elements below the fold. - **browser_wait** — Wait for an element to appear on the page. Supports CSS and text-based selectors. - **browser_hover** — Hover over an element to trigger tooltips, dropdown menus, or hover states. Supports CSS and text selectors. If the mouse would not reach the target at its center - another element lies in front of it (an overlay, a dialog's backdrop), or the target does not take clicks there (pointer-events, visibility, clipping) - the answer is ok:false with error "covered" and covered_by. Found before the mouse is sent, nothing is sent; if it comes in front afterwards, the rest of the mouse movement is stopped and the answer also has maybe_landed: true, because the page may already have reacted. - **browser_select_option** — Select an option from a dropdown menu. Works with native inside it; (2) if there is none, clicks the target and intercepts the NATIVE OS file-chooser it opens - pass the selector of the button that opens the dialog, and the file is supplied programmatically without the dialog ever appearing. Other file inputs on the page do not get the file: when neither strategy works, the error lists them in other_file_inputs, each with a `selector` to pass if it is the right field - a CSS selector that matched that input alone when the tool looked (built from its id, its name or its position on the page), or null when none did, for instance for an input inside a shadow root. The answer describes the input that got the file in `input`. If the field is empty afterwards although the page's change handler saw the file in it, the answer is ok with cleared_by_page: true and seen_in_field - X and Facebook empty the field after reading the file, and a page that rejects the file can do the same, so check the page before attaching again. Files must be regular files inside the working directory the MCP server runs in - folders, symlinks and hardlinks that point outside it are refused. - **browser_set_date** — Robustly set a date input - handles native , masked text inputs (e.g. MM/DD/YYYY), and calendar pickers (MUI, react-datepicker, AntD, Lexical/Meta). Tries native value-set, format-aware typing via Input.insertText, and ARIA-based picker navigation in sequence with read-back verification. Use instead of browser_fill when fill fails or for any input that opens a calendar widget. - **browser_handle_dialog** — Answer a JavaScript alert/confirm/prompt or "Leave site?" on the active tab. If a dialog this extension saw open is on screen and nobody is answering it, it is answered now, and the reply says what Chrome reports happened (action accept or dismiss). Otherwise this arms automatic handling of the next dialog on the tab and returns immediately - call it BEFORE the click that opens the dialog, because a dialog freezes the tab. Pass wait=true only when the dialog is already opening. Errors: dialog-being-answered (browser_navigate or an earlier call is answering it - wait), dialog-unconfirmed (answered, but Chrome did not confirm it closed), tab-not-responding (a dialog that opened before anything listened, or a busy page; the note says what to do). - **browser_wait_for_network** — Wait for a network request to complete. Useful after clicking buttons that trigger API calls - ensures data is loaded before reading the page. Monitors real network traffic via Chrome DevTools Protocol. - **browser_fetch** — Make an HTTPS request from the extension background. It is not subject to the page's CORS or CSP, so it works for API calls (Google, Stripe, Slack) where a fetch from the page would be blocked. Your browser cookies are not sent and the answer's cookies are not stored: pass a token in headers. Plain http works only to 127.0.0.1. - **browser_list_tabs** — List the tabs this session owns (tabs it opened or adopted): id, URL, title, and each tab's active flag (whether Chrome shows it in front of its window, not which tab this session is working in). Tabs of other sessions are not included. - **browser_get_cookies** — Get cookies for a site this session has open in one of its tabs (the site itself, a parent domain or a subdomain). Navigate to the site first - cookies for sites the session is not working on are refused. - **browser_get_local_storage** — Read localStorage from the current page. Pass key for a specific value, or omit for all. - **browser_set_cookies** — Set one or more cookies for a domain. - **browser_set_local_storage** — Set a localStorage key-value pair on the current page. - **browser_console_logs** — Get recent console.log/warn/error messages from the page. Installs a lightweight interceptor on first call. Returns the last N console messages. - **browser_ask_user** — Ask the user to do something or give information. Without fields it shows a small card in the bottom-left corner that the user can drag away while they act on the page (log in, solve a CAPTCHA, give consent); with fields it shows a dialog over the page. The prompt is drawn again after a navigation in the tab, but a prompt with fields ends with action navigated if the tab moves to another origin (another domain, subdomain or port) or, on a local file, to another file. Returns acknowledged, action (done, skip, timeout, tab_closed, replaced when a newer question in the same tab takes over, navigated, or removed_by_page when the page keeps removing the prompt) and, for done, values. The page cannot read the field values, but it can see the keystrokes, so ask only for secrets that belong to the page the tab is on. The tab must show a page that loaded (a web page or a local file): on Chrome's error page or about:blank the call fails at once and shows nothing. It makes the tab the active one in its window and restores a minimized window, but it does not bring Chrome in front of other apps. - **browser_list_frames** — List all frames (iframes) in the current page with their URLs and indices. - **browser_select_frame** — Execute JavaScript in a specific iframe by frame index. Use browser_list_frames first to find the right index. - **browser_get_new_tab** — Get the most recently opened tab (useful after clicking links that open new tabs, OAuth popups, etc.). - **browser_switch_tab** — Switch to a specific browser tab by ID. Get tab IDs from browser_list_tabs or browser_get_new_tab. The other tools then act on that tab. Chrome is not brought in front of the user: the tab is made active in its window, and visibility says whether the page is hidden behind other windows. - **browser_close_tab** — Close a browser tab by ID. Only tabs owned by the current session can be closed. - **browser_upload_file** — Handing a file to the page needs "Allow access to file URLs" for the Agent360 Browser MCP extension (off by default for Chrome Web Store installs); that switch also lets the extension open any local file as a page, so whether to turn it on is the user's call. A "Not allowed" error from the handoff is reported as file-access-off unless Chrome confirms that file access is on. Upload a file to a element on the page. Uses Chrome Debugger API to set files programmatically - no dialog needed. For drag-drop zones without visible file input use browser_drop_file. If the field is empty afterwards although the page's change handler saw the file in it, the answer is ok with cleared_by_page: true and seen_in_field - X and Facebook empty the field after reading the file, and a page that rejects the file can do the same, so check the page before attaching again. Files must be regular files inside the working directory the MCP server runs in - folders, symlinks and hardlinks that point outside it are refused. - **browser_extract_token** — Open a known provider's API page (stripe, hubspot, slack, shopify, mailchimp, pipedrive, calendly, google, linkedin) and get instructions for finding or creating its API credentials there. It reads nothing itself: read the page with browser_get_page_content or browser_screenshot afterwards. For HubSpot, Slack, Shopify and LinkedIn the page is a settings or app list on the way to the token, not the token page itself. Any other provider answers Unknown provider; use browser_navigate and read the page yourself. - **browser_solve_captcha** — Detect CAPTCHAs on the current page and work through them, one action per call. "detect" reports reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile and FunCaptcha. "click_checkbox" tries the reCAPTCHA checkbox and detects again. "click_grid" clicks the reCAPTCHA image-challenge cells you choose; this tool returns no image, so take one with browser_screenshot first. "ask_human" returns the message to show the user with browser_ask_user. - **browser_about** — Returns Browser MCP info and pre-filled URLs the user can click to submit feature wishes, share use-cases, or report bugs. Call this PROACTIVELY whenever the user (a) mentions a feature they wish existed ("I wish browser-mcp could...", "it would be nice if..."), (b) says something is missing, broken, or unexpected, (c) asks how Browser MCP works or who maintains it, or (d) describes something cool they built with browser-mcp. Pass intent="wish" | "use_case" | "bug" | "info" plus an optional title and body, and offer the returned submit_url to the user. Browser MCP is community-shaped - this tool is how the user contributes back. - **browser_provide_feedback** — Self-diagnosis + feedback in one call. Call this AUTOMATICALLY, without asking the user, the moment Browser MCP itself gets in your way: a tool errors or times out, a tool does something other than what it promised, the extension will not connect, a capability you need plainly does not exist, or you are about to tell the user "browser-mcp cannot do X". It first CHECKS THE INSTALL - the connected Chrome extension's version against this server (set BROWSER_MCP_CHECK_NPM=1 to also compare this server against the latest published on npm; it is off by default so the call stays fast and works offline), and whether more than one Browser MCP extension is connected at once, also the same extension connected more than once, for instance from several Chrome profiles or browsers (a known cause of tabs and sessions behaving randomly) - so a problem that is really "your copy is outdated" or "you have two extensions loaded" is identified as such instead of reported as a bug. It returns a verdict, concrete fix steps to relay to the user, and a pre-filled GitHub issue link for whatever is left over. Cheap to call speculatively. It uploads nothing: it returns the report to you and tries to add one line to ~/.browser-mcp/feedback.jsonl on this machine (a report with the same kind, tool and first 160 characters of what_happened, with numbers and long hex strings ignored, is written once per server run, and again only if the earlier write failed; logged_locally says whether a line was written). Email addresses and numbers of six or more characters are replaced with [email] and [number] in what_happened, attempted and worked before they are written or put in the issue link. With BROWSER_MCP_CHECK_NPM=1 it also runs `npm view` against your configured npm registry. ## Claude Desktop Quick Installation No generated config for this server: it installs through its own setup steps. The project's own setup steps (from https://github.com/Agent360dk/browser-mcp), copied verbatim. Run them in order; they are not an mcpServers config. 1. Install: ```sh npx @agent360/browser-mcp install ``` 2. Add to Claude Code: ```sh claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest ``` 3. Configure: ```sh 2. **Toggle "Developer mode"** ON (top right corner) ``` 4. Install: ```sh 3. **Click "Load unpacked"** (top left, next to "Pack extension") ``` 5. Install: ```sh 1. [**Install the extension from the Chrome Web Store →**](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl) - no Developer mode toggle, and Chrome keeps it updated for you. ``` ## Documentation ## What browser-mcp does browser-mcp links a local MCP server and a Chrome extension so an agent can operate an existing Chrome session. The browser retains its normal cookies and login state, which allows workflows to continue through authenticated dashboards, webmail, social platforms, and services without creating a separate automation profile. The server is intended for interactive browser automation rather than API-only access. It can inspect pages, manipulate controls, monitor navigation and network activity, and return screenshots or page data. Agents can also ask the user to complete a step in the visible browser, such as entering a 2FA code, solving a CAPTCHA, granting consent, or making a sensitive choice. ## How it works Two components are required: the local MCP process that the client launches and the Agent360 Chrome extension that drives the browser. The extension may be installed from the Chrome Web Store or loaded as an unpacked extension. The MCP server is installed from the npm package and registered in the MCP client's configuration. Sessions can use Chrome tabs organized into separate, color-coded groups, allowing multiple agents to work at once. The server can list tabs belonging to its session, adopt or work with the active tab, and keep browser interaction tied to the user's real Chrome environment. User prompts are displayed in the browser window. They can include fields when the agent needs information, while page navigation can cause prompts to be redrawn or completed with a navigation status. ## Setup and configuration Install the Chrome extension first, either from the Chrome Web Store or by loading the extension directory in `chrome://extensions` with Developer mode enabled. Then register the local server with an MCP client. For Claude Code, the documented command is: ```bash claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest ``` Restart the client after registering the server. A setup command can also place the unpacked extension at `~/.browser-mcp/extension/` and register the server with supported clients it detects. The extension alone is not sufficient; it needs the local MCP server to connect. ## Tools and capabilities - Navigate tabs and verify whether a page loaded, including handling blocked unloads and browser dialogs. - Read page text or HTML, target a CSS selector, and extract rows from long or virtualized lists by scrolling. - Click, double-click, right-click, hover, scroll, fill fields, select options, set dates, choose autocomplete values, and press keyboard keys. - Capture visible screenshots, execute JavaScript expressions, inspect console messages, and wait for elements or network requests. - Manage tabs, cookies, local storage, file uploads, dialogs, overlays, and user prompts. - Send HTTPS requests from the extension background when page CORS or CSP would block a page-origin request; cookies are not sent automatically. - Recover a stalled debugger attachment and use coordinate-based clicks when normal element targeting cannot reach a control. ## Limitations and notes Screenshots require a visible, uncovered Chrome window. Background tabs cannot provide wheel-driven loading or rendering behavior needed by some virtualized lists. Page reads are capped by default at 30,000 characters, so large documents may need selector-based reading or list extraction. File upload requires files inside the MCP server's working directory and may require enabling file access for the extension. Native operating-system context menus are not opened by the right-click tool; it targets menus rendered inside the page. Browser requests made with `browser_fetch` require headers for authentication because the browser's cookies are neither sent nor stored. The server is released under the MIT license and runs locally. Windows unpacked-extension installation is identified as not yet verified in the project instructions. _Full upstream README: https://allmcps.com/mcp/browser-mcp/readme_