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.

Related MCP server: js-reverse-mcp

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

Navigation and interaction

Reverse-engineering toolkit

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.