Skip to content
Back to search

browser-tools-mcp

Monitor browser logs directly from Cursor and other MCP compatible IDEs.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agentdeskai--browser-tools-mcp/badge.svg)](/listings/agentdeskai--browser-tools-mcp)

HTML

<a href="/listings/agentdeskai--browser-tools-mcp"><img src="/api/listings/agentdeskai--browser-tools-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Two pieces: an MCP server (one command) and a Chrome extension.

1. Point your MCP client at the server

{
  "mcpServers": {
    "browser-tools": {
      "command": "npx",
      "args": ["-y", "@agentdeskai/browser-tools-mcp@latest"]
    }
  }
}

On Windows, if your client cannot find `npx`, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@agentdeskai/browser-tools-mcp@latest"]`.

Requires **Node 22.19 or newer**. Check with `node --version`; if you use nvm or asdf, make sure your editor inherits the same version.

2. Load the Chrome extension

1. Download or clone this repository. 2. Open `chrome://extensions` and turn on **Developer mode**. 3. Choose **Load unpacked** and select the `chrome-extension` directory.

That is the whole setup. **There is no second server to start** — the MCP server runs the connector itself.

3. Use it

Open Chrome DevTools (F12) on the page you want to inspect. Capture begins as soon as DevTools is open; the **BrowserTools** panel is only for settings and status. Then ask your agent something like *"check the console for errors"* or *"run an accessibility audit on this page"*.

Not working? Run `npx @agentdeskai/browser-tools-mcp --doctor`, which reports exactly which piece is missing.

To watch capture happen live — useful when checking a fresh install — start the connector with `--verbose`:

npx @agentdeskai/browser-tools-server --verbose
· console error tab 42 Uncaught TypeError: total is not a function
· network 500 POST tab 42 https://myapp.local/api/pay (1310ms)

Without it the connector only reports connect and disconnect, so a working setup and a silent one look the same.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 288 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # BrowserTools MCP
  2. **If you are still on 1.x, upgrade.** 1.x is unsupported. It has known critical
  3. vulnerabilities (remote code execution, unauthenticated access to captured
  4. data) that were fixed in 2.0 and will not be patched on 1.x. See
  5. [SECURITY.md](SECURITY.md) and [MIGRATION.md](MIGRATION.md).
  6. Give your AI coding agent eyes on the browser. BrowserTools MCP streams console
  7. output, network activity, screenshots and Lighthouse audits from **your real
  8. Chrome session** — the one already logged into your app — to any MCP-compatible
  9. client: Cursor, Claude Code, Windsurf, Cline, Zed, Gemini CLI, and others.
  10. > **Version 2.0 is a rewrite.** One process instead of three, no unauthenticated
  11. > local server, credentials scrubbed before they leave the browser, and a real
  12. > test suite. Coming from 1.x? Read [MIGRATION.md](MIGRATION.md).
  13. ---
  14. ## Why this instead of a CDP-based server
  15. Tools like Chrome DevTools MCP and Playwright MCP drive a *fresh, automated*
  16. browser. That is the right choice for writing tests. It is the wrong choice for
  17. debugging the app you are actually looking at, because since Chrome 136 the
  18. browser refuses remote debugging on your default profile — the one holding your
  19. logins. So you end up recreating your auth state in a throwaway profile before
  20. you can debug anything.
  21. BrowserTools attaches to the session you are already in, through a DevTools
  22. extension. You stay logged in, on the page you were already on, and your agent
  23. reads what you see. It also reports Lighthouse-grade performance, accessibility
  24. and SEO data, which the automation-first servers do not.
  25. ## Install
  26. Two pieces: an MCP server (one command) and a Chrome extension.
  27. ### 1. Point your MCP client at the server
  28. ```json
  29. {
  30. "mcpServers": {
  31. "browser-tools": {
  32. "command": "npx",
  33. "args": ["-y", "@agentdeskai/browser-tools-mcp@latest"]
  34. }
  35. }
  36. }
  37. ```
  38. On Windows, if your client cannot find `npx`, use `"command": "cmd"` with
  39. `"args": ["/c", "npx", "-y", "@agentdeskai/browser-tools-mcp@latest"]`.
  40. Requires **Node 22.19 or newer**. Check with `node --version`; if you use nvm or
  41. asdf, make sure your editor inherits the same version.
  42. ### 2. Load the Chrome extension
  43. 1. Download or clone this repository.
  44. 2. Open `chrome://extensions` and turn on **Developer mode**.
  45. 3. Choose **Load unpacked** and select the `chrome-extension` directory.
  46. That is the whole setup. **There is no second server to start** — the MCP server
  47. runs the connector itself.
  48. ### 3. Use it
  49. Open Chrome DevTools (F12) on the page you want to inspect. Capture begins as
  50. soon as DevTools is open; the **BrowserTools** panel is only for settings and
  51. status. Then ask your agent something like *"check the console for errors"* or
  52. *"run an accessibility audit on this page"*.
  53. Not working? Run `npx @agentdeskai/browser-tools-mcp --doctor`, which reports
  54. exactly which piece is missing.
  55. To watch capture happen live — useful when checking a fresh install — start the
  56. connector with `--verbose`:
  57. ```
  58. npx @agentdeskai/browser-tools-server --verbose
  59. ```
  60. ```
  61. · console error tab 42 Uncaught TypeError: total is not a function
  62. · network 500 POST tab 42 https://myapp.local/api/pay (1310ms)
  63. ```
  64. Without it the connector only reports connect and disconnect, so a working
  65. setup and a silent one look the same.
  66. ## Tools
  67. | Tool | What it does |
  68. | --- | --- |
  69. | `getConsoleLogs` | Console output, filterable by keyword with paging |
  70. | `getConsoleErrors` | Error-level output and uncaught exceptions |
  71. | `getNetworkLogs` | XHR/fetch requests with status, timing and bodies |
  72. | `getNetworkErrors` | Only failed and 4xx/5xx requests |
  73. | `getSelectedElement` | The element selected in the Elements panel |
  74. | `getPageInfo` | Which page the browser is currently on |
  75. | `getConnectionStatus` | Whether the extension is connected, and capture counts |
  76. | `listBrowserTabs` | Tabs with DevTools open, addressed by a DevTools-connected `tabId` |
  77. | `listTabs` | Tabs `chrome.tabs` returns (not every open tab), addressed by `chromeTabId` |
  78. | `readTab` | Headings, excerpt, and a snapshot of a `chromeTabId`, without the debugger |
  79. | `navigateBrowser` | Load a URL in a DevTools-connected tab, without focusing it |
  80. | `navigateTab` | Load a URL in the background from `listTabs`, visible window only |
  81. | `softClick` / `softType` | Untrusted click or type. Result is `worked` or `needs a real gesture` |
  82. | `takeScreenshot` | Screenshot returned **as an image**, plus its file path |
  83. | `refreshBrowser` | Reloads the inspected tab |
  84. | `getBrowserStorage` | localStorage, sessionStorage and cookies (values gated) |
  85. | `wipeLogs` | Clears captured telemetry before a clean reproduction |
  86. | `runAccessibilityAudit` | Lighthouse accessibility audit |
  87. | `runPerformanceAudit` | Lighthouse performance audit with Core Web Vitals |
  88. | `runSEOAudit` | Lighthouse SEO audit |
  89. | `runBestPracticesAudit` | Lighthouse best-practices audit |
  90. Three prompts ship alongside them — `debuggerMode`, `auditMode` and
  91. `nextjsSeoAudit` — giving your agent a systematic workflow instead of a wall of
  92. static text in every tool listing.
  93. All tools declare MCP output schemas, so clients receive structured data rather
  94. than prose they have to parse, and read-only tools are annotated as such so
  95. clients can auto-approve them safely.
  96. ### Tabs without DevTools
  97. `listTabs`, `readTab`, `navigateTab`, `softClick`, and `softType` use `chrome.tabs` and `chrome.scripting`. They do not attach the debugger, so they do not show the debugging banner, and they do not activate a tab or focus a window.
  98. `chromeTabId` comes from `listTabs`. `tabId` on the other tools comes from `listBrowserTabs`. They are different id spaces. Pass each id only to the tool that issued it.
  99. `listTabs` reports the tabs `chrome.tabs` returns in the windows it returns. Other Arc Spaces, Little Arc, pinned favorites, split-view partners, and slept tabs may be missing. Incognito is skipped. This is not every open tab. Background navigation stays in the visible window until that is measured on Arc.
  100. The popup switch has to be on. Navigation and soft input also need `--allow-input` on `browser-tools-mcp`, or `--allow-actions` on the `browser-tools` CLI. The same origin rules as other input apply. An asleep tab is reported and not reloaded. A soft action says `worked` or `needs a real gesture` and does not claim a failed action worked.
  101. ### Several tabs at once
  102. Every tab with DevTools open is tracked separately. Telemetry is attributed to
  103. the tab that produced it, and retention is per tab, so a chatty page cannot push
  104. out the history of the one you care about.
  105. Tools act on the **current tab** — the one you most recently opened DevTools on.
  106. A tab whose connection drops and comes back does not steal that position, which
  107. is what used to make screenshots capture the wrong page. Every result reports
  108. the `tabId` and `url` it came from, plus `otherTabs`, so a wrong-tab answer is
  109. visible rather than silent. To target a specific tab, call `listBrowserTabs` and
  110. pass its `tabId` to any tool; pass `allTabs: true` to read across every tab.
  111. ### Large data stays out of the context window
  112. Whole-history payloads are exposed as MCP **resources** rather than inlined, and
  113. tools link to them with `resource_link` so your agent fetches them only when it
  114. decides to:
  115. | Resource | What it is |
  116. | --- | --- |
  117. | `browser-tools://console/{tabId\|all}` | Every console entry, with no per-call budget |
  118. | `browser-tools://network/{tabId\|all}` | Every captured request, including bodies |
  119. | `browser-tools://har/{tabId\|all}` | The same traffic as a HAR 1.2 file |
  120. | `browser-tools://screenshot/{name}` | A screenshot you captured earlier |
  121. | `browser-tools://audit/{reportId}` | The unabridged Lighthouse result behind a summary |
  122. Log tools attach a link when a read had to be cut short; network reads always
  123. offer the HAR; screenshots always link to the stored image, which is the only
  124. way to see one too large to inline. The last 20 full Lighthouse reports are kept
  125. under `audits/` in the screenshot directory.
  126. ### Keeping responses small
  127. Log payloads are the usual cause of a blown context window. Every read tool
  128. takes `limit` and `offset`, and the log tools take keyword filters:
  129. ```
  130. getConsoleErrors({ keywords: ["hydration"], limit: 20 })
  131. getNetworkLogs({ urlKeywords: ["/api/"], bodyKeywords: ["quota"], limit: 10 })
  132. ```
  133. Results are returned newest-first and always report `total` alongside
  134. `returned`, so an agent knows when it is only seeing part of the picture.
  135. ## Privacy and security
  136. This tool captures whatever your browser sees, so it treats that data carefully:
  137. - **Loopback only.** The connector binds `127.0.0.1` and refuses non-loopback
  138. addresses. In 1.x it bound `0.0.0.0`, reachable by anyone on your network.
  139. - **The extension never leaves loopback.** 1.x scanned private network ranges
  140. and adopted whichever host answered with a known string — meaning anyone on
  141. shared Wi-Fi could receive your logs and screenshots. That scan is gone.
  142. - **Authenticated.** The HTTP API requires a per-run bearer token. A token in
  143. the URL is refused. The extension WebSocket requires the same token; the
  144. extension collects it from a loopback pairing route that answers only a
  145. browser-extension origin, and `/.identity` does not reveal it. Pass
  146. `--extension-id` to accept one extension and no others.
  147. - **Credentials are scrubbed** on the way in: `Authorization`, `Cookie` and
  148. similar headers, plus JWTs, cloud keys and vendor tokens found anywhere in
  149. captured strings, become `[REDACTED]`.
  150. - **Headers are off by default**, per direction, and storage values are withheld
  151. unless explicitly requested.
  152. - **Cookie access is an optional permission** you grant from the panel, not
  153. something the extension holds by default.
  154. - **The debugger banner stays visible.** Chrome's "started debugging this
  155. browser" warning is a safety control. It is intentional, and this project
  156. never hides it. A capture path that does not attach the debugger simply
  157. does not raise the banner; that is not a way to silence it.
  158. - **Audits stay off your internal network.** An audit accepts a url, and the
  159. caller may be a model reading untrusted pages. Link-local and cloud metadata
  160. addresses are never audited. Pages on localhost or a private network are
  161. audited only while open in a connected tab (or allowlisted with
  162. `--audit-allow-origin`), and every request the audit browser makes —
  163. redirects and subresources included — is checked again as it happens. A
  164. local page may load only the local origins that are open in a tab or
  165. allowlisted, so if your app calls an API on another local port, open that
  166. too or allowlist it. Audits connect directly, not through a system proxy.
  167. Behind a fake-IP proxy (Clash, sing-box, Surge), which hides where names
  168. really go, audits are refused unless you pass
  169. `--audit-allow-private-network`; see SECURITY.md.
  170. Report vulnerabilities per [SECURITY.md](SECURITY.md).
  171. ## Configuration
  172. Flags, or the matching `BROWSER_TOOLS_*` environment variables:
  173. | Flag | Purpose |
  174. | --- | --- |
  175. | `--port <n>` | Connector port (default 3025) |
  176. | `--screenshot-dir <path>` | Where screenshots are written |
  177. | `--only <a,b>` | Expose only these tools, on MCP and on the local API |
  178. | `--exclude <a,b>` | Hide these tools, on MCP and on the local API |
  179. | `--allow-actions` | Let the local API reload, capture, wipe, change settings and select a tab. Otherwise confirm that in the BrowserTools panel. The MCP tools in the process that embeds the connector are not gated by this |
  180. | `--extension-id <id>` | Only this extension may pair and connect |
  181. | `--doctor` | Check the setup and exit |
  182. | `--verbose` | Print each captured entry as it arrives |
  183. | `--host <addr>` | Loopback address to bind (default `127.0.0.1`) |
  184. | `--connect <url>` | Attach to a connector already running elsewhere |
  185. | `--token <t>` | Auth token to use with `--connect` |
  186. | `--no-redact` | Disable credential scrubbing (not recommended) |
  187. | `--audit-allow-origin <o,o>` | Loopback/private origins audits may target or load without an open tab |
  188. | `--audit-allow-private-network` | Let audits reach any loopback/private address except the audit's own ports (not recommended); also needed behind a fake-IP proxy |
  189. To share one browser session between several MCP clients, start the connector
  190. once with `npx @agentdeskai/browser-tools-server` and every client will attach to
  191. it automatically. The local API uses the `--only`, `--exclude`,
  192. `--allow-actions` and `--extension-id` of that process. An attached client's
  193. `--only` / `--exclude` still hide tools from that client.
  194. ## Known limits
  195. - Network capture starts when DevTools opens. Requests that finished before then
  196. are not recorded — reload the page to capture a full page load.
  197. - Screenshots are held to a byte budget (`screenshotMaxBytes`, 3 MB by default).
  198. A capture that would exceed it is re-encoded as JPEG and, if still too large,
  199. downscaled. A viewport capture of dense content on a high-DPI display can
  200. otherwise run past 13 MB, which is more than a model's context can take and
  201. past the read buffer newer MCP stdio transports enforce. If an image still
  202. cannot fit, it is written to disk and the tool returns the path instead of
  203. inlining it.
  204. - Console capture defaults to the DevTools protocol, which makes Chrome show a
  205. "started debugging this browser" banner. That banner is intentional and is
  206. never hidden. Switch the panel's capture mode to **Wrap page console** to
  207. capture the console without attaching the debugger.
  208. - **Firefox is not verified.** The extension is written cross-browser — a
  209. `browser`/`chrome` shim, `browser_specific_settings`, and a capture mode that
  210. does not need `chrome.debugger` — but it has never been loaded in Firefox, and
  211. nothing in the test suite covers it. Screenshots in particular go through the
  212. DevTools protocol and will not work there. Treat Firefox as unsupported until
  213. someone has actually run it; a report either way is welcome.
  214. - Audits launch a separate browser and take up to a minute. Any Chromium-based
  215. browser works — Chrome, Chromium, Brave, Edge, Vivaldi, Opera or Arc — and
  216. `--doctor` reports which one will be used. Set `CHROME_PATH` to override.
  217. Arc is supported on a best-effort basis and has not been verified headless.
  218. ## Development
  219. ```bash
  220. npm install
  221. npm run build
  222. npm test # unit + integration, no browser required
  223. npm run test:e2e # real Chromium with the extension loaded (headless)
  224. ```
  225. `npm test` runs in seconds. The end-to-end suite launches Chromium with the
  226. extension installed, drives fixture pages, and asserts the whole capture path.
  227. It runs headless; set `HEADED=1` to open a visible window. Run
  228. `npx playwright install chromium` first.
  229. ## License
  230. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.