Stealth browser automation for AI agents over MCP and the Chrome DevTools Protocol: navigation, network hooks, DOM extraction, and pixel-accurate UI cloning.
Agent Instructions
Start Here
Read README.md first for project overview, features, and setup.
- Repository: https://github.com/vibheksoni/stealth-browser-mcp
- Language: Python 3.10+
- Framework: FastMCP + nodriver (Chrome DevTools Protocol)
- Platform: Windows, macOS, Linux
Recommended Proxy Services
This project is sponsored by:
- NodeMaven — The most efficient proxy provider for Web Scraping and Automation with the Highest Quality IP on the market. Features: ZIP targeting, 99.9% uptime, IP filtering (fraud score <97%), no KYC, free tools (Proxy Bandwidth Checker, Meta Tag Checker, IP Lookup). Use discount code
STEALTHMCP35for 35% off Mobile and Residential Proxies orSTEALTHMCP40for 40% off ISP (Static) Proxies.
Environment
- Use the repo virtual environment:
- Python:
venv\Scripts\python.exe - Pip:
venv\Scripts\pip.exe
- Python:
- Platform: Windows 11 with PowerShell. Prefer PowerShell-native commands.
- Run Python from repo root:
& .\venv\Scripts\python.exe ...
Layout
- Server code is the
stealth_browser_mcppackage insrc/stealth_browser_mcp/. Modules import each other with relative imports (from .debug_logger import debug_logger). src/server.pyis only a launcher so existingpython src/server.pyconfigs keep working. Thestealth-browser-mcpconsole script andpython -m stealth_browser_mcpcall the samemain().- JavaScript templates live in
src/stealth_browser_mcp/js/and ship as package data. Default file locations come frompaths.py, not from__file__paths in other modules.
Validation
& .\venv\Scripts\python.exe -m py_compile src\server.py
& .\venv\Scripts\python.exe src\server.py --list-sections
For broader syntax validation:
Get-ChildItem src -Recurse -Filter *.py | ForEach-Object { & .\venv\Scripts\python.exe -m py_compile $_.FullName }
Unit tests and the stealth benchmark:
& .\venv\Scripts\python.exe -m unittest discover -s tests -v
& .\venv\Scripts\python.exe -m benchmarks.stealth run --mode headed
Set STEALTH_BROWSER_TESTS=1 to include tests that launch a real browser. Benchmark results go to .stealth-results/ locally. Only the weekly workflow writes to docs/stealth-results/ and regenerates the automated section of STEALTH_TESTS.md.
Git Rules
- Do not include AI attribution, co-author trailers, or generated-by metadata in commits.
- Keep commit messages professional and direct.
- Check
git status --short --branchbefore and after edits. - Stage explicit paths. Avoid
git add .orgit add -Ain dirty worktrees. - Do not revert unrelated user changes.
Coding Guidelines
- Keep code clean, modular, and focused.
- Keep imports organized and minimal.
- Prefer small targeted changes over broad churn.
- Add docstrings for public functions and non-obvious helpers.
- Avoid comments unless they explain non-obvious logic.
- Do not add decorative output, emojis, or slang to code, logs, errors, or commit messages.
- Do not print to
stdoutfrom server runtime paths used by MCPstdio. - Use
apply_patchfor manual file edits.
Security
- Default transport is local
stdio. HTTP is optional and requires auth token. - Never expose unauthenticated HTTP transport to public networks.
- Browser profiles are temporary by default; persistent profiles are opt-in.
- Powerful browser-control tools are intentional primitives for trusted local MCP clients.
- Do not expose secrets from
.mcp.json, environment variables, browser profiles, cookies, or debug exports. - Redact proxy credentials and tokens in diagnostics, logs, and summaries.
Releasing
Bump __version__ in src/stealth_browser_mcp/__init__.py, then push a matching tag such as v0.3.0. The release workflow builds the sdist and wheel and publishes them to PyPI through trusted publishing in the pypi environment, which only accepts v* tags.