stealth-chrome-devtools-mcp MCP Server

Undetectable browser automation for AI agents via the Model Context Protocol.

A self-containedstealth Chrome DevTools MCP serverwith smart profile management, anti-detection stealth arg filtering, and robust process lifecycle handling. Built onnodriver(CDP-based) for full anti-bot evasion.

https://github.com/user-attachments/assets/c4de61ae-6878-4fff-9bfd-65cdd4fadc2f

https://github.com/user-attachments/assets/f81fc0c2-9233-48cd-8a9d-2577b1d33d57

Add to your MCP config (claude_desktop_config.json,.claude/settings.json, etc.):

{ "mcpServers": { "stealth-chrome-devtools-mcp": { "command": "uvx", "args": ["stealth-chrome-devtools-mcp==2.0.6"] } } }

pip install stealth-chrome-devtools-mcp==2.0.6

Crashes are reported to the maintainers by default, with your username and machine name scrubbed out. SeeError Reportingfor what a report contains and how to turn it off.

{ "mcpServers": { "stealth-chrome-devtools-mcp": { "command": "uv", "args": [ "--directory", "/path/to/stealth-chrome-devtools-mcp", "run", "stealth-chrome-devtools-mcp" ] } } }

Clones exclude regenerable Chrome caches, so each is a few MB rather than multiple GB. Disposable auto-clones are deleted on close, and a storage cap (STEALTH_MCP_CLONE_STORAGE_CAP_GB, default 10 GB) reclaims the oldestidleclones if any ever leak — sosessions/stays bounded. Cap eviction isrecoverable: an evicted clone is moved intosessions/.trash/and only purged after a retention window (STEALTH_MCP_CLONE_TRASH_RETENTION_HOURS, default 24 h), so a mistaken eviction can be restored rather than lost.

Named profiles you create explicitly (e.g.github-session) persist and are never deleted. But even a "persistent" profile is ~98% regenerable (caches plus Chrome's multi-GB on-device AI model). So whensessions/exceedsSTEALTH_MCP_BROWSER_SESSION_STORAGE_CAP_GB(default 20 GB), the largestidlenamed profiles are trimmed of those regenerable dirs whileevery login is preserved— Chrome rebuilds them on next launch. In-use profiles are never touched.

The server automatically strips Chrome flags that would compromise stealth:

Stripped args are reported inspawn_diagnostics.stealth_args_stripped.

On server restart, the process cleanup system:

- Reaps only browsers whoseowner backend is dead— every tracked browser records which backend started it, so two backends running side by side never reap each other's browsers
- Keepscreate_timetracking as a second net: never kills a process that startedafterthe current server session began
- Safely handlespsutil.AccessDeniedon Windows elevated processes

Headed Browsing and Where the Window Opens

A headed browser appears on the desktop of whichever processlaunchedit, not of whichever session asked. Because sessions share a backend, a backend that was first started from an SSH login or a Windows service session cannot show a window to anyone — including the sessions running on the physical desktop.

So the backend is keyed bydisplay context: one per desktop, plus one for a headless context. Discovery prefers a backend that can show a window, which means an SSH-drivenspawn_browser(headless=False)automatically uses the desktop backend and its window opens on the real screen. Where no such backend exists, the spawnraisesinstead of handing back an invisible browser; runstealth-chrome-devtools doctorto see which contexts have a backend. Headless spawns work from anywhere.

# Spawn with default master profile spawn_browser() # Named session with login persistence spawn_browser(user_data_dir="github-session") # Same name while first is open → auto-suffixes to github-session-2 spawn_browser(user_data_dir="github-session") # Headless with stealth (bad args auto-stripped) spawn_browser(headless=True, browser_args=["--enable-automation"]) # → stealth_args_stripped: ["--enable-automation stripped: sets navigator.webdriver=true"]

94 toolsacross 11 sections — the count is derived from the live tool registry, never hand-maintained.See the full navigation map →.

That is what the serverserves, which is not the same as what the release gateproves. At the release SHA in the evidence ledger, 3 of those 94 are release-qualified: asserted end-to-end over the real stdio transport a client actually speaks. The rest are driven against real Chrome by the E2E suite but through an in-process seam, so they areserved-unqualifiedat the wire — tested, not proved there.RELEASE_CONTRACT.mdlists the state of each tool and is the only source for those numbers.

# Unit tests only (no Chrome needed) uv run pytest -m "not integration" # All tests (needs Chrome installed) uv run pytest # Verbose with short tracebacks uv run pytest -v --tb=short

If your checkout path contains spaces or an&,uv run pytestfails withFailed to canonicalize script path— use the venv Python directly:.venv\Scripts\python.exe -m pytest -m "not integration". See CONTRIBUTING.mdfor the full test/gate workflow.

A comprehensive suite covers stealth arg filtering, profile resolution, orphan recovery, storage-cap sweeps, the ops CLI, and full browser integration.

All optional. Defaults work for normal use. Set them in your shell, or in~/.stealth-mcp/.env— every key is documented in .env.example.

A.envin yourprojectdirectory is deliberately ignored. The backend is a shared process launched with whatever folder your MCP client had open, so reading the project's.envmeant reading someone else's application config — which crashed the server outright on an ordinaryDATABASE_URLand silently adopted that app'sPORT,DEBUG, andSENTRY_DSNas the server's own.

Installs astealth-chrome-devtoolsops command for managing the server and its disk usage. (This is forops— to drive a browser, use the MCP server or its HTTP backend.)

These four only read and preview — they change nothing, and the test suite runs them on every commit, so they are known to work:

stealth-chrome-devtools status stealth-chrome-devtools profiles stealth-chrome-devtools cleanup stealth-chrome-devtools cleanup --browser-session-cap-gb 12

statusreports whether the backend is up plus the browser-session root and both caps;profileslists profiles with size / role / in-use;cleanuppreviews the reclaimable disk (dry run), and--browser-session-cap-gbpreviews it at a tighter cap.

These are not auto-executed —--applydeletes,servedoes not return, anddoctorneeds Chrome installed:

stealth-chrome-devtools cleanup --apply # actually reclaim stealth-chrome-devtools doctor # check Chrome / environment stealth-chrome-devtools serve --http --port 19222 # start the server

cleanupdeletes idle auto-clones over the clone cap and trims idle named profiles down to their session state —logins kept— over the browser-session cap. It is adry run unless you pass--apply, never touches in-use profiles, and uses the same selectors as the automatic sweep, so the preview matches--apply.

- Python 3.11+
- Chrome, Chromium, or Microsoft Edge
- uv(recommended) or pip
- A desktop session forheadedbrowsing (headless works from SSH, CI, and services)

Crashes and errors are reported to Sentryby default, so that a failure you hit is a failure we can see and fix. There is nothing to install and nothing to configure: the SDK ships with the package and the destination is built in.

What a report contains.The exception type and message, the stack trace, the package version, and the platform. Three things are kept out of it:

That is universal — it runs on every install, ours included, and there is no way to opt back into sending those fields. What it deliberately leaves alone is the part that makes a report useful: the error type, the module path after the home segment, the source line that failed, and the release it came from.

An error message still quotes whatever the failing call was working with — a URL you navigated to, a file you asked for. If that is not a trade you want to make, turn reporting off.

To turn it off, set one variable in your shell or in~/.stealth-mcp/.env:

Earlier releases readSENTRY_DSNfrom the environment. They no longer do — that variable belongs toyourapplication, and a shared backend launched from your project folder was picking it up. See Environment Variablesfor why this tool ignores your project's.enventirely.

git clone https://github.com/DevinoSolutions/stealth-chrome-devtools-mcp cd stealth-chrome-devtools-mcp uv sync --extra dev --extra test # install linters + test deps npm install # arm husky pre-commit/pre-push hooks

The six quality gates run automatically on every commit: ruff format, ruff check, ty check, vulture, suppression-owner check, file-budget check. Unit tests run on pre-push.

- CLAUDE.md— navigation map of the source tree + glossary + conventions
- DESIGN.md— architecture invariants and thewhybehind them
- RUNBOOK.md— operating the backend: verbs, logs, recovery, MCP smoke path
- CONTRIBUTING.md— clone → install → test, the quality gate, conventions

Official Playwright MCP server for browser automation, page inspection, screenshots, and web interaction from Claude, Cursor, and other AI agents.

Render website screenshots with ScreenshotOne

Attaches to existing browser sessions using the Chrome DevTools Protocol for automation and interaction.

Help your AI agent finish more browser tasks.

Automate remote browsers using the BrowserCat API.

Remote browser automation using the BrowserCat API.

Take screenshots and read console logs from web pages using Playwright.

Automate browser tasks using the Browser Use API.

A Node.js server that enables AI assistants to control the Chrome browser via WebSocket. Requires the CodingBaby Chrome Extension.

A configurable MCP server for browser automation using Puppeteer.

stealth-chrome-devtools-mcp

About

Details

Jump to

Setup

Headed Browsing and Where the Window Opens

About

Details

Jump to

Setup

Headed Browsing and Where the Window Opens

More like this

@mendableai/firecrawl Mcp Server

Umut Naci

Playwright

Sentry

Github

Fetch