browser-mcp

browser-mcp is a small browser-runtime MCP server for coding agents. It connects directly to a Chrome DevTools Protocol (CDP) endpoint and exposes eight high-level tools instead of mirroring the very large CDP API.

Tools

All potentially large outputs have hard limits. Network output intentionally excludes headers such as Authorization and Cookie.

Related MCP server: chrome-devtools-mcp

Requirements

• Node.js 22 or newer

• Chrome, Chromium, or Chrome for Testing with a CDP HTTP endpoint

• Cursor or another MCP client that supports stdio servers

Chrome 136 and newer ignore --remote-debugging-port for the normal Chrome profile. Use a separate --user-data-dir, which is also the safer way to give an agent runtime access.

Install and build

npm install
npm run build

The ordinary settings are at the top of src/config.ts. The CDP endpoint defaults to http://127.0.0.1:9222; set BROWSER_CDP_URL only when a different local endpoint is needed.

Start Chrome with CDP

Close or leave your ordinary Chrome untouched, then start a separate debugging profile.

macOS:

open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/browser-mcp-profile

Linux:

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/browser-mcp-profile

Windows PowerShell:

& "$env:ProgramFiles\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:TEMP\browser-mcp-profile"

Open http://127.0.0.1:9222/json/list to verify that Chrome is exposing tabs.

Configure Cursor

Create or edit .cursor/mcp.json in the project that should use the tools. Replace the path with the absolute path to this project.

{
  "mcpServers": {
    "browser-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/browser-mcp/dist/server.js"],
      "env": {
        "BROWSER_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

Restart or reload Cursor after changing the configuration. Cursor CLI users can verify the registration with agent mcp list-tools browser-mcp.

Suggested agent flow

The server sends model-facing instructions with its MCP initialization response. They tell the agent to treat the user as an active debugging partner and use page-runtime or two-phase coordination instead of guessing. No workflow depends on the client rendering an input or confirmation form.

For element work:

1. get_pages

2. inspect_page when the target is already identifiable

3. For phrases such as “this logo”, the agent tells the user what to click and calls pick_element({ interaction_prompt: "Click the logo you mean · Esc to cancel" })

4. The browser page displays that instruction, highlights hovered elements, and waits for a click

5. The same tool call returns the clicked element's selector, tag, text, box, and clipped HTML; Escape cancels

6. inspect_element, evaluate, and screenshot can then analyze, test, and verify the change

get_pages refreshes the default page on every call. It prefers the page for which document.hasFocus() is true and visibilityState is visible; if Chrome reports no focused page, it falls back to the first current /json/list page. Passing page_id targets only that tool call and never changes the default. Call get_pages again after the user opens or switches tabs when subsequent calls will omit page_id.

For a network action:

1. get_pages

2. The agent calls get_network({ capture_action: "start" }) and retains the signed captureId

3. The agent tells the user in ordinary chat exactly what browser action to perform; the page displays a green capture-active banner

4. After the user reports completion, the agent calls get_network({ capture_action: "finish", capture_id: "...", ...filters })

5. The finish call returns only requests whose event sequence began after the start boundary

The same start/chat/finish transaction works for console output with get_console. Results include startedAt, finishedAt, and per-event sequence numbers. Filters are evaluated on the finish call, so repeat the desired filters there.

The older wait_for_next mode remains available when the desired endpoint is one specific event rather than a user-confirmed capture window. wait_until controls whether a network wait ends when the request starts, its response arrives, or loading finishes.

Calling pick_element without interaction_prompt uses the default page banner. Supplying it changes only the banner text; both paths use the same blocking page-runtime picker. A client's tool-permission prompt merely authorizes execution and is not treated as interaction completion. For less common DOM events, evaluate can install a one-shot event listener and return a Promise that resolves after the user action.

Console and network capture begin when get_pages (or the first page-specific tool) attaches to the tab. They cannot reconstruct events that Chrome no longer has after a disconnected session.

v0.5.0 boundaries

• Direct CDP-over-WebSocket connection only. Chrome 144's consent-based --autoConnect flow for attaching to an ordinary running profile is not implemented in this version.

• The main frame and open shadow roots are inspectable. Cross-origin iframe contents require a later multi-target implementation.

• get_network returns metadata, not response bodies or WebSocket frames.

• pick_element waits up to two minutes; click an element or press Escape.

• evaluate is intentionally powerful and can mutate the page or read data available to page JavaScript. Use a dedicated debugging profile.

Development

npm test

The test suite covers the MCP tool catalog, CDP command/event transport, output limits, selector interpolation safety, and an end-to-end fake-CDP flow through all eight runtime operations.

References

• Chrome DevTools Protocol

• Chrome 136 remote-debugging profile change

• Chrome 144 consent-based active-session connection

• MCP TypeScript SDK

• Cursor MCP documentation