seleniumbase-mcp — SeleniumBase CDP Mode as an MCP server

An MCP server that exposes SeleniumBase's CDP Mode (undetected, driverless Chrome automation) to any MCP client — Claude Code, Claude Desktop, Cursor, or your own agent.

Beyond the usual click/type/screenshot tools, it ships a JavaScript reverse-engineering toolkit: grep across a page's bundles, dump a function's source, hook a function to record its arguments, and intercept fetch/XHR to discover a site's private API — all without pulling megabytes of minified code into the model's context.

Também disponível em português.

Why CDP Mode

SeleniumBase's CDP Mode drives Chrome over the DevTools Protocol with no WebDriver attached, which gets past most bot detection that trivially flags Selenium and Playwright. This server keeps that property intact and adds multi-browser session management on top.

Features

• Many browsers at once. Every browser is named by a browser_id you choose, so one agent can drive several, and several agents can share one server without stepping on each other.
• Thread-per-browser isolation. Each browser owns a dedicated thread and event loop — required, because SeleniumBase's CDP layer calls loop.run_until_complete internally and would deadlock inside FastMCP's loop.
• Context-frugal reverse engineering. The RE tools run JavaScript inside the page and return only the match, the slice, or the payload you asked for.
• stdio or HTTP. Run one server per client for full isolation, or one shared HTTP server for several clients.

Install

git clone https://github.com/ileonzin/seleniumbase-mcp.git
cd seleniumbase-mcp
pip install -r requirements.txt

Requires Python 3.10+ and a local Chrome installation.

Register with a client

Claude Code

claude mcp add seleniumbase-cdp -- python /absolute/path/to/seleniumbase-mcp/sb_mcp_server.py

Claude Desktop / any client with a JSON config

{
  "mcpServers": {
    "seleniumbase-cdp": {
      "command": "python",
      "args": ["/absolute/path/to/seleniumbase-mcp/sb_mcp_server.py"]
    }
  }
}

Restart the client; the tools appear as mcp__seleniumbase-cdp__*.

Shared HTTP server (several clients, one browser pool)

python sb_mcp_server.py --http --port 8765

claude mcp add --transport http seleniumbase-cdp http://127.0.0.1:8765/mcp

Give each client its own browser_id prefix (agent1-main, agent2-main) so they don't collide.

Tools

Lifecycle

Tool	What it does
browser_open(browser_id, url, headless, incognito, proxy)	Launch a CDP-mode Chrome under a name you pick
browser_close(browser_id)	Close it and free the Chrome process
browser_list()	Names of all open browsers

Navigation and interaction

Tool	What it does
navigate(browser_id, url)	Go to a URL, returns the landed URL
click(browser_id, selector)	Click the first CSS match
type_text(browser_id, selector, text)	Type into a field
get_text(browser_id, selector)	Visible text of an element
get_html(browser_id)	Full page source
current_url(browser_id)	Current URL
eval_js(browser_id, script)	Evaluate JS, return the value
wait_for_element(browser_id, selector, timeout)	Wait until visible
screenshot(browser_id)	PNG returned as an image

Reverse-engineering toolkit

Tool	What it does
list_scripts(browser_id)	Inventory of <script> tags — URLs, sizes, same-origin flags. No content, just the map.
get_script(browser_id, target, offset, length)	Read one script by index or URL substring, paginated. Same-origin only (CORS blocks the rest).
grep_js(browser_id, pattern, flags, max_hits, max_script_kb)	Regex every inline and same-origin script; returns matching lines with file and line number.
get_fn_source(browser_id, expression)	toString() any live function — window.app.encrypt, JSON.parse, anything defined.
hook_fn(browser_id, path)	Wrap a function so its calls are recorded (args + return). Cleared on navigation.
get_hook_log(browser_id, clear)	Last 200 recorded calls.
network_log(browser_id, enable)	Install fetch/XHR interceptors to record URL, method, body, status.
get_network(browser_id, clear)	Last 200 captured requests.

Example: find out how a site signs its API calls

browser_open(browser_id="re", url="https://target.example")
network_log(browser_id="re")                       # start watching traffic
click(browser_id="re", selector="#search-button")  # trigger the action
get_network(browser_id="re")                       # → POST /api/v2/search, X-Sig header
grep_js(browser_id="re", pattern="X-Sig|signature")
get_fn_source(browser_id="re", expression="window.__app.sign")
hook_fn(browser_id="re", path="__app.sign")        # capture real inputs
get_hook_log(browser_id="re")
browser_close(browser_id="re")

The model sees a handful of matched lines and one function body instead of a 3 MB bundle.

Notes and limits

• Prefer headless=False on anti-bot sites. CDP Mode is meaningfully more stealthy with a visible window.
• Cross-origin scripts are unreadable by get_script and grep_js — the page's own fetch is subject to CORS. They're reported under unreadable.
• hook_fn captures the return value synchronously. For an async function you get the Promise object, not its resolution; the arguments — the usually interesting part — come through fine.
• Hooks die on reload. Both hook_fn and network_log patch live objects, so navigation or a reload wipes them. Re-install after navigating.
• Every browser_open starts a real Chrome process. Close what you open.

Intended use

Built for authorized work: testing your own sites, scraping where you have permission, security research, and understanding APIs you're allowed to integrate with. Respect the terms of service and the law of whatever you point it at.

License

MIT — see LICENSE.