Stealth browser automation for AI agents over MCP and the Chrome DevTools Protocol: navigation, network hooks, DOM extraction, and pixel-accurate UI cloning.
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and adheres to Semantic Versioning where practical.
[Unreleased]
Added
PyPI package -
pipx install browserstealthmcpinstalls astealth-browser-mcpcommand, anduvx browserstealthmcpruns it without installing. The PyPI name differs becausestealth-browser-mcpon PyPI belongs to an unrelated project. Installing from the GitHub URL works too. MCP clients can use"command": "stealth-browser-mcp"instead of a venv interpreter and script path.python -m stealth_browser_mcpworks too. The code moved into a realstealth_browser_mcppackage undersrc/, the JavaScript templates ship as package data, andpyproject.tomlhas a build system and console script.python src/server.pystill works for existing configs (#38).STEALTH_BROWSER_MCP_DATA_DIR- Sets where element clones and large responses are written. An installed package defaults to the per-user data directory, and the file upload allowlist defaults to anuploadsfolder inside it. A clone keeps using the repo root for both.press_key()tool - Presses real keys through CDPInput.dispatchKeyEvent, producing trustedkeydown/keypress/keyupevents. Supports named keys (Enter, Tab, Escape, arrows, Backspace, Delete, Home, End, PageUp, PageDown, Space, F1-F12), single printable characters, modifier combinations (Shift, Control/Ctrl, Alt, Meta/Cmd), optional focus selector, repeat count, and inter-press delay.Tests -
tests/test_press_key.pycovers the key-to-CDP mapping, the modifier bitmask, and the dispatch sequence. A browser-backed test assertingisTrustedruns whenSTEALTH_BROWSER_TESTS=1is set.Stealth benchmark -
python -m benchmarks.stealthruns the browser against a bundled local probe, an init script capability check, Sannysoft, Intoli, CreepJS, Cloudflare (nowsecure.nl), and the tls.peet.ws TLS and HTTP/2 fingerprint API. Each target reports PASS, DEGRADED, FAIL, or UNREACHABLE with its individual checks, and each run writes a JSON result file. A weekly GitHub Actions workflow runs it on Linux, Windows, and macOS in headless and headed mode plus the previous Chrome release, commits results todocs/stealth-results/, regenerates the automated section ofSTEALTH_TESTS.md, and opens astealth-regressionissue when a target gets worse (#25).STEALTH_BROWSER_EXECUTABLE- Environment variable that selects the browser executable instead of auto-detection.Screenshot images -
take_screenshotreturns MCP image content with metadata instead of base64 text, scales large captures down to fit client limits instead of writing a file on the server, and acceptsquality(JPEG, 1 to 100) andmax_widthto shrink images. Thanks to @bepcyc (#37).Page bindings -
create_page_binding,get_page_binding_calls,resolve_page_binding_call, andremove_page_bindinglet page JavaScript callwindow.<name>(...args)and get a Promise that the agent answers. Calls are queued as JSON (64 KB per call, 500 queued per instance),auto_resolveanswers immediately with a fixed value, and bindings follow every tab and navigation. Nothing runs on the server host. This replacescreate_python_binding.BROWSER_TAB_RECYCLE_NAVIGATIONS- Opt-in main tab recycling. It was always on at 25 navigations before.Launch flags benchmark target - Fails when the real Chrome command line has automation, sandbox-disabling, or unsupported flags.
Input fidelity benchmark target - Checks that
click_elementandtype_textproduce trusted events in a real order without touching the page DOM.Tests -
tests/test_js_values.py,tests/test_element_cloners.py, andtests/test_hooks_and_proxy.pycover result conversion, template escaping, cloner data paths, hook matching, proxy parsing, and debug log export. CI now runs the unit test suite.
Fixed
- macOS disk leak - Chrome on macOS copied its whole app bundle into a
code_sign_clonefolder at every launch and only removed it on a clean exit, so crashed or killed instances left about 1 to 2 GB behind each time. Chrome now starts withMacAppCodeSignCloneturned off, merged into a single--disable-featuresswitch with nodriver's defaults and any caller features. Verified on a macOS runner with Chrome 155: one leftover clone per killed launch before, none after (#40). - README images on PyPI - The logo, sponsor banner, demo GIF, and showcase image use absolute GitHub URLs, so they show on the PyPI page instead of breaking. The version badge shows the PyPI release instead of a stale 0.2.5, and file links point at GitHub.
- Fresh installs -
mcpis pinned to 1.30.0.mcp2.x removed names that fastmcp 2.11.2 imports, so an unpinned install could fail at startup.py2jsnow comes from PyPI (1.2.1, the same code as the old git pin), so installing no longer needs git, andpydanticis 2.12.5, which has Python 3.14 wheels. - Sandbox flags - Chrome keeps its sandbox on Windows and macOS, including under an administrator account. Only Linux as root or in a container gets
--no-sandbox.--disable-setuid-sandbox,--single-process, and--disable-gpuare no longer added anywhere, so headed windows no longer show the "unsupported command-line flag" bar, tabs no longer share one crash-prone process in containers, and WebGL stays available. - Browser startup - Chrome gets up to 30 seconds to start instead of under 3, which cold CI runners and slow disks missed. A failed start no longer leaves a Chrome process and temp profile behind, and Chrome's output goes to the null device instead of an unread pipe that could fill up and block it.
- Trusted clicks -
click_elementscrolls the element into view, moves the mouse along a short path, and presses and releases the button with CDP input events, so pages see trustedpointerdown,mousedown,mouseup, andclickevents. It used to callel.click()from JavaScript, which produces an untrusted click with no mouse events, and nodriver's click flashed a highlight element into the page DOM. Covered or hidden elements still fall back to a JavaScript click. - Trusted typing -
type_textsends keydown, keypress, input, and keyup for every character, holds Shift for capitals and symbols, and inserts other characters like an input method. It used to send barecharevents. Clearing a field now selects the content and presses Backspace, so React and other frameworks see the change.parse_newlinesandshift_enterpress real Enter and Shift+Enter keys. - Speed -
navigatereturns in about 30 ms on a simple page instead of about 550 ms,close_instancetakes about 0.2 s instead of hitting a 5 s timeout every time,click_elementdropped its fixed 0.5 s wait,list_tabsandnew_tabno longer wait 0.5 s per tab, andwait_for_elementpolls every 100 ms without fetching the whole DOM tree. Element lookups for click, type, paste, and key presses fetch only the document root. - Network hooks - Fetch interception is enabled only while a hook applies to the instance, so pages without hooks no longer pause every request twice. Hooks created after spawn now update the interception patterns of running instances, and removing the last hook turns interception off.
- Network capture memory - Only text-like response bodies (documents, XHR, fetch, scripts, JSON, text, XML) are stored, up to 2 MB each and 64 MB per instance, oldest dropped first. Images, media, and fonts are fetched on demand instead of copied for every request. Stored bodies also serve
get_response_contentafter the page has moved on. Chrome internal URLs are no longer captured. - Tab state - Timezone override, extra headers, init scripts, network capture, and page bindings are applied to every tab the instance uses, including tabs opened with
new_tab, switched to, or created to replace a closed or crashed tab. A replaced tab used to silently lose the timezone override and headers.new_tabconfigures the tab before loading the URL. - Closed tab recovery - Tools recover when the page closes its own tab or the tab crashes, opening a new window when the last one is gone.
- Persistent functions -
create_persistent_functionnow really survives reloads and new tabs, validates the name and code, and keeps the function out ofObject.keys(window). - Cleanup - Every close path (tool, idle reaper, shutdown) clears network data, persistent functions, and bindings for the instance. Shutdown and idle reaping close instances in parallel, and nodriver's target refresh tasks no longer error after the browser exits.
- Headless detection - Headless instances no longer report
HeadlessChromeinnavigator.userAgent, worker user agents, or theUser-Agentheader. The real headless user agent is read once per browser build and launched with the headless marker removed, unless a customuser_agentis set. Headless runs of the stealth benchmark went from 2 of 7 targets passing to 7 of 7, including CreepJS (67% headless to 0%) and the SannysoftHEADCHR_UAandCHR_MEMORYchecks. - Execution contexts -
get_execution_contextsreturns the real CDP contexts for every frame and isolated world instead of a single fake entry.context_id(numeric id or unique id) is now honored bydiscover_global_functions,inject_and_execute_script, andexecute_function_sequence. - Tabs -
close_tabmoves the instance to another open tab when the current tab is closed, and closing the last tab leaves a blank tab so the browser stays usable. - Responsiveness - Browser process and profile cleanup runs in a worker thread, so closing an instance no longer freezes other tool calls for several seconds.
- Authenticated proxies - Plain HTTP requests through an authenticated proxy no longer fail with 407 after the first request on a keep-alive connection. CONNECT responses are checked by status code.
- Script results -
execute_scriptreturns plain JSON values instead of raw CDP deep-serialized nodes, and reports JavaScript exceptions as failures instead of success. - Element cloning - Selectors are JSON-escaped in every extractor, so quotes and backslashes work. Progressive
expand_*tools,extract_complete_element_to_filesummaries, CDP matched styles, andclone_element_to_filesub-extractors now return real data. File tools no longer save extraction errors as successful files. - Broken tools -
extract_element_assets,extract_related_files, anddiscover_object_methodsno longer crash on an invalidawait.set_cookie(same_site=...),spawn_browser(extra_headers=...), andnavigate(referrer=...)no longer fail on CDP type errors. Browser state, cookie, and network resources serialize correctly. - Navigation -
wait_until="load"and"domcontentloaded"wait for the page event instead of returning immediately. The referrer applies to the navigation only and no longer replaces spawn-time headers. - Page tools -
reload_pagehonorsignore_cache,take_screenshothonorsformatandfull_page,select_optionworks by text and can be called repeatedly,scroll_pageaccepts negative amounts, andwait_for_elementrespects short timeouts. - Network capture - Resource types are recorded, so capture filters and type searches work.
response_containsonly matches captured bodies. Captured requests are capped per instance and bodies are read after loading finishes. - Dynamic hooks - Resource type and custom conditions match as documented,
|alternatives work in URL and method requirements, global hooks apply to new instances, response headers are passed to hooks, compile errors are reported, and simple hook values can no longer inject code. - Process cleanup - Owner liveness checks work on Windows, the shared PID file is written atomically, and a reused PID is never killed during recovery.
- Proxies - Percent-encoded proxy credentials are decoded, and proxy errors no longer include passwords.
- Debug logs - Exporting logs no longer deadlocks the server, log lists are capped, and
max_errors=0returns no entries. - Python in browser - The final expression is translated once instead of being re-run as raw Python.
get_instance_stateaccepts fractionaldevicePixelRatiovalues.
Changed
STEALTH_TESTS.mdnow leads with generated benchmark results. The 2026-02-10 manual snapshot is kept below it, and the X.com section no longer implies an Arkose challenge was solved.add_script_to_evaluate_on_new_documentlogic moved intoBrowserManager.add_init_scriptso the benchmark tests the same code path, and installed scripts are re-applied to new and replacement tabs.- The MCP server instructions no longer claim instances are undetectable and point to the measured results instead.
element-interactionsection now exposes 13 tools; full surface is 101 tools, minimal surface is 21.- HTTP transport binds to
127.0.0.1by default and warns on stderr when bound to another host without an auth token. hot_reloadrefuses to run while browser instances are open, so they are not orphaned.- Removed the unused
response_stage_hooksmodule and unused JavaScript templates.
Removed
create_python_binding- Removed for security. It ran arbitrary Python from the client on the server host withexec(), any website could call the binding it exposed, and the bridge never delivered calls to Python. Use the page binding tools instead.
Notes
type_text(parse_newlines=True)now presses a real Enter key for each newline. Usepress_key()for other control keys in React-select and typeahead widgets (Greenhouse, Ashby, Lever, Workday).
[0.2.5] - 2026-02-10
Fixed
- MCP JSON-RPC Protocol Corruption - All debug
print()calls redirected from stdout to stderr, fixing tool hangs afterspawn_browserandnavigate(#8) - Python Version Requirement - Corrected
requires-pythonfrom>=3.8to>=3.10(fastmcp requires 3.10+) - Missing Dependency - Added
uvicorn[standard]to pyproject.toml (was only in requirements.txt) - SECURITY.md Branch Reference - Fixed
maintomaster
Added
- Microsoft Edge Support - Automatic browser detection for Chrome, Chromium, and Edge (thanks @Hamza5)
- Troubleshooting Section - Common issues and fixes documented in README
Changed
- README Rewrite - Reduced from 706 to 468 lines; removed duplicate tool listings, stale labels, and excessive emojis
- Hall of Fame - Replaced fabricated testimonials with real contributor table and verified use cases
- Example Prompts - Stripped marketing hype, kept practical copy-paste prompts
- Repo Cleanup - Removed internal Checklist.md from tracking, updated Discord links
[0.2.4] - 2025-08-11
Fixed
- π‘οΈ Root User Browser Spawning - Fixed "Failed to connect to browser" when running as root/administrator
- π Args Parameter Validation - Fixed "Input validation error" for JSON string args format
- π³ Container Environment Support - Added Docker/Kubernetes compatibility with auto-detection
- π§ Cross-Platform Compatibility - Enhanced Windows/Linux/macOS support with platform-aware configuration
Added
- π
validate_browser_environment_tool()- New diagnostic tool for environment validation - βοΈ Smart Platform Detection - Auto-detects root privileges, containers, and OS-specific requirements
- π Flexible Args Parsing - Supports JSON arrays, JSON strings, and single string formats
- π Enhanced Logging - Added platform information to browser spawning debug logs
- π οΈ
platform_utils.py- Comprehensive cross-platform utility module
Enhanced
- Browser Argument Handling - Automatically merges user args with platform-required args
- Environment Detection - Detects root/administrator, container environments, and Chrome installation
- Error Messages - More descriptive error messages with platform-specific guidance
- Sandbox Management - Intelligent sandbox disabling based on environment detection
Technical
- Added
merge_browser_args()function for smart argument merging - Added
is_running_as_root()cross-platform privilege detection - Added
is_running_in_container()for Docker/Kubernetes detection - Enhanced
spawn_browser()with comprehensive args parsing - Improved browser configuration with nodriver Config object
- Total tool count increased from 89 to 90 tools
[0.2.3] - 2025-08-10
Added
- β‘
paste_text()function - Lightning-fast text input via Chrome DevTools Protocol - π Enhanced
type_text()- Addedparse_newlinesparameter for proper Enter key handling - π CDP-based text input - Uses
insert_text()method for instant large content pasting - π‘ Smart newline parsing - Converts
\nstrings to actual Enter key presses when enabled
Enhanced
- Text Input Performance -
paste_text()is 10x faster than character-by-character typing - Multi-line Form Support - Proper handling of complex multi-line inputs and text areas
- Content Management - Handle large documents (README files, code blocks) without timeouts
- Chat Application Support - Send multi-line messages with preserved line breaks
Technical
- Implemented
DOMHandler.paste_text()usingcdp.input_.insert_text() - Enhanced
DOMHandler.type_text()with line-by-line processing for newlines - Added proper fallback clearing methods for both functions
- Updated MCP server endpoints with new
paste_texttool - Updated tool count from 88 to 89 functions
[0.2.2] - 2025-08-10
Added
- ποΈ Modular Tool System - CLI arguments to disable specific tool sections
- β‘ --minimal mode - Run with only core browser management and element interaction tools
- π --list-sections - List all 11 tool sections with tool counts
- π§ Granular Control - Individual disable flags for each of 11 tool sections:
--disable-browser-management(11 tools)--disable-element-interaction(10 tools)--disable-element-extraction(9 tools)--disable-file-extraction(9 tools)--disable-network-debugging(5 tools)--disable-cdp-functions(13 tools)--disable-progressive-cloning(10 tools)--disable-cookies-storage(3 tools)--disable-tabs(5 tools)--disable-debugging(6 tools)--disable-dynamic-hooks(10 tools)
- ποΈ Clean Architecture - Section-based decorator system for conditional tool registration
Changed
- Updated CLI help text to show "88 tools" and new section options
- Reorganized tool registration using
@section_tool()decorator pattern - All tools now conditionally register based on disabled sections set
Technical
- Implemented
DISABLED_SECTIONSglobal set for tracking disabled functionality - Added
is_section_enabled()helper function - Created
@section_tool("section-name")decorator for conditional registration - Tools are only registered if their section is enabled
[0.2.1] - 2025-08-09
Added
- π Dynamic Network Hook System - AI-powered request/response interception
- π§ AI Hook Learning System - 10 comprehensive hook examples and documentation
- β‘ Real-time Processing - No pending state, immediate hook execution
- π Custom Python Functions - AI writes hook logic with full syntax validation
- π§ Hook Management Tools - Create, list, validate, and remove hooks dynamically
Fixed
- RequestId type conversion issues in CDP calls
- Missing imports in hook learning system
- Syntax errors in browser manager integration
- Smithery.ai deployment Docker build failure - Added
gitto Dockerfile system dependencies for py2js installation - Smithery.ai PORT environment variable support - Server now reads PORT env var as required by Smithery deployments
- Docker health check endpoint - Updated health check to use correct /mcp endpoint with dynamic PORT
Changed
- Replaced old network hook system with dynamic architecture
- Updated documentation to reflect new capabilities
- Removed 13 broken/incomplete network hook functions - Moved to
oldstuff/old_funcs.pyfor reference - Corrected MCP tool count to 88 functions - Updated all documentation consistently
Removed
create_request_hook,create_response_hook,create_redirect_hook,create_block_hook,create_custom_response_hook- These functions were calling non-existent methodslist_network_hooks,get_network_hook_details,remove_network_hook,update_network_hook_status- Management functions for the broken hook systemlist_pending_requests,get_pending_request_details,modify_pending_request,execute_pending_request- Pending request management (replaced by real-time dynamic hooks)
[0.2.0] - 2025-08-08
Added
- Initial dynamic network hook system implementation
- Real-time request/response processing architecture
[0.1.0] - 2025-08-07
Added
- Initial public README overhaul
- Community health files (CoC, Contributing, Security, Roadmap, Changelog)
- Issue and PR templates