What is Browser Mcp Over Cdp

browser-mcp-over-cdp is an MCP Server that manages a Chrome browser using the Chrome DevTools Protocol (CDP). It provides tools for navigating, interacting with, and accessing a browser tab remotely.

Use cases

Use cases include automated testing of web applications, capturing full-page screenshots for documentation, analyzing accessibility features of web pages, and performing remote debugging of web applications.

How to use

To use browser-mcp-over-cdp, first set up the Selenoid Selenium Hub by running specific Docker commands. Then, install the necessary NodeJS packages and configure the paths in the config-example.json file. Finally, access the live browser through the provided URL.

Key features

Key features include full-height screenshots of web pages, an accessibility tree, enriched deep DOM representation, interaction capabilities via clicks and keyboard inputs, and basic navigation functions like opening URLs and reloading pages.

Where to use

browser-mcp-over-cdp can be used in web development, automated testing, accessibility testing, and any scenario requiring remote browser management and interaction.

Browser MCP over CDP

MCP Server that manages a Chrome browser using the Chrome DevTools Protocol (CDP)

This project exposes tools to navigate, interact and access a browser tab. The browser is controller using CDP and because of this:

1. the page is exported as full height screenshoot, accessibility tree and enriched deep DOM
   1. the screenshoot captures whole page, not just the visible scrolled are
   2. the accessibility tree contains most relevand parts
   3. the enriched deep DOM contains
      1. nested iframes, shadow DOM, pseudo-elements, etc.
      2. per element attached listeners (for e.g. onClick, onKeyDown, etc), including the callback function code (for better or for worse)
      3. per element relevant resolved styles
2. the page is interactable via click, keys and input value update functions
3. the page is navigable with basic open URL, back, forward and reload functions

Prereq

1. NodeJS

Use with local Chrome

1. npm install
2. put config-example.json configuration inside Cloude, VS Code, Cursor, wherever you want.
   1. for Cloude see https://modelcontextprotocol.io/quickstart/user
   2. for Cursor see https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers

Use with remote Chrome

1. run Selenoid Selenium Hub by running the below command inside “selenoid” dir:

   docker pull selenoid/vnc_chrome:128.0
   docker pull selenoid/hub
   docker pull aerokube/selenoid-ui
   docker-compose up -d
   

2. specify the Selenium HUB address via SELENIUM_HUB_URL env var by adding inside config-example.json/mcpServers/browser the following:

   "env": {
       "SELENIUM_HUB_URL": "http://localhost:4444/wd/hub"
   }
   

3. to see the live browser go to http://localhost:8080/

Warnings

The Selenoid Selenium Hub configuration uses docker.sock from the host, so it has full control over Docker.

Troubleshoot

npx @modelcontextprotocol/inspector npx tsx /Users/bogdan/devel/browser-mcp-over-cdp/src/MCP.ts