mcp-patchright-mainworld

🛡️ Undetectable browser MCP server — 66 tools, Patchright-powered, zero CDP fingerprint.

![npm] ![MCP]

Passes Cloudflare / Akamai / Kasada / Datadome.

Fork of mcp-patchright that adds a per-call world: "main" option to browser_evaluate / browser_run_code_unsafe, so page-defined window globals are visible and callable. Defaults to Patchright's isolated stealth world (matching upstream); opt into main only when a page's own script needs to see or be called by your evaluated code. Everything else matches upstream mcp-patchright.

Why Patchright, not Playwright?

| | Playwright | Patchright | |---|---|---| | Runtime.enable | ✅ sends (detectable) | ❌ removed | | Console.enable | ✅ sends | ❌ removed | | --enable-automation flag | ✅ present | ❌ removed | | navigator.webdriver | true | false / undefined | | Anti-bot evasion | ❌ | ✅ |

See the full comparison for details.

Quick start

npm i -g mcp-patchright-mainworld
mcp-patchright-mainworld --port 9321 --host 127.0.0.1

With Claude / GPT / agents

{
  "mcpServers": {
    "patchright": {
      "command": "npx",
      "args": ["mcp-patchright-mainworld", "--port", "9321", "--host", "127.0.0.1"]
    }
  }
}

Features

• 66 MCP tools — full browser automation surface
• world: "main" opt-in — browser_evaluate / browser_run_code_unsafe can run in the page's real world to see/call page-defined globals (default stays isolated/stealth)
• browser_find — search the current aria snapshot for text/regex, cheaper than a full browser_snapshot
• browser_save_blob — save a Blob/data URL produced by page code to disk
• 3 transports — stdio, SSE, Streamable HTTP (/mcp)
• Persistent profiles — real Chrome profile, reuse across sessions
• Multi-page — tab management (new, list, switch, close)
• Owner-scoped HTTP sessions — isolate tabs per caller with owner query/header
• CDP attach — control an already-running Chrome
• Network tracking + interception — request list/detail, offline toggle, block/mock routes
• Session import/export — browser_storage_save / browser_storage_load (cookies + localStorage)
• Granular storage — per-key cookie / localStorage / sessionStorage CRUD (browser_cookie_*, browser_localstorage_*, browser_sessionstorage_*)
• Authenticated API requests — browser_api_request reuses session cookies (hybrid scraping)
• Text/HTML extraction — browser_get_visible_text / _html (token-light)
• Iframe-aware — pass frameSelector to any element tool (click/fill/type/hover/press/wait_for/select/drag) to act inside an iframe
• PDF export — browser_save_pdf via CDP (works in headed/stealth mode)
• Video recording — browser_start with recordVideo, browser_video_save; .webm flushed on browser_close
• Element highlight — browser_highlight / browser_hide_highlight overlays for screenshots & recordings
• Stealth profiles — proxy / geolocation / locale / timezone / colorScheme
• Console capture — real-time console message stream
• Fingerprint check — browser_fingerprint_check diagnostics
• Virtual passkeys — create, import, list, and delete WebAuthn credentials with private keys redacted by default

Tools

Full comparison HTML in /docs/tool-comparison.html.

• browser_start
• browser_status
• browser_navigate
• browser_new_page
• browser_pages
• browser_switch_page
• browser_close_page
• browser_snapshot
• browser_find
• browser_take_screenshot
• browser_click
• browser_fill
• browser_type
• browser_hover
• browser_press_key
• browser_wait_for
• browser_evaluate
• browser_fingerprint_check
• browser_navigate_back
• browser_select_option
• browser_handle_dialog
• browser_file_upload
• browser_network_requests
• browser_network_request
• browser_console_messages
• browser_resize
• browser_drag
• browser_fill_form
• browser_run_code_unsafe
• browser_add_init_script
• browser_network_state_set
• browser_api_request
• browser_get_visible_text
• browser_get_visible_html
• browser_iframe_click
• browser_iframe_fill
• browser_route_block
• browser_route_mock
• browser_route_clear
• browser_storage_save
• browser_storage_load
• browser_cookie_list
• browser_cookie_get
• browser_cookie_set
• browser_cookie_delete
• browser_cookie_clear
• browser_localstorage_list
• browser_localstorage_get
• browser_localstorage_set
• browser_localstorage_delete
• browser_localstorage_clear
• browser_sessionstorage_list
• browser_sessionstorage_get
• browser_sessionstorage_set
• browser_sessionstorage_delete
• browser_sessionstorage_clear
• browser_passkey_install
• browser_passkey_create
• browser_passkey_list
• browser_passkey_delete
• browser_video_save
• browser_highlight
• browser_hide_highlight
• browser_save_blob
• browser_save_pdf
• browser_close

Development

Owner-scoped HTTP sessions

HTTP mode requires a stable owner on the MCP URL (?owner=<id>) or with the X-Browser-Owner header. Page listing, switching, navigation, and closing are restricted to that owner's tabs. Delete /owners?owner=<id> to close all tabs owned by one caller without stopping the browser or clearing the profile.

npm install
npm run build
node dist/index.js

Release

Install the matching Chromium build once, then prepare a release from the exact dependency versions in package-lock.json, run the full verification suite, and inspect the package without publishing it:

npx patchright install chromium
npm run release:check
npm publish

By default, browser_start launches Chromium via patchright as headed real Chrome with a persistent profile at:

~/.maestro/stealth-playwright-mcp/profiles/default

You can override it with the userDataDir tool argument or STEALTH_PLAYWRIGHT_USER_DATA_DIR.

To attach to an already-running Chrome instead of launching one, start Chrome with remote debugging and pass cdpEndpoint to browser_start:

google-chrome --remote-debugging-port=9222 --user-data-dir=$HOME/.maestro/stealth-playwright-mcp/profiles/cdp

{ "cdpEndpoint": "http://127.0.0.1:9222" }

browser_snapshot returns Playwright's AI aria snapshot. Use [ref=eN] values from that snapshot with browser_click, browser_fill, browser_type, browser_hover, browser_press, and browser_wait_for by passing { "ref": "eN" }. CSS selectors remain supported via { "selector": "..." }.

MCP config example:

{
  "mcpServers": {
    "patchright": {
      "command": "node",
      "args": ["/path/to/mcp-patchright-mainworld/dist/index.js"]
    }
  }
}

Direction

Shipped:

• ✅ persistent user data dirs
• ✅ CDP attach to real Chrome
• ✅ proxy / timezone / locale / geolocation profiles
• ✅ accessibility snapshots for LLM-friendly page control
• ✅ fingerprint diagnostics
• ✅ network interception (block / mock)
• ✅ session import/export (storageState)
• ✅ PDF export
• ✅ authenticated API requests (reuse browser cookies)
• ✅ lightweight text/HTML extraction
• ✅ iframe actions
• ✅ world: "main" opt-in for browser_evaluate / browser_run_code_unsafe
• ✅ aria-snapshot search (browser_find)
• ✅ save Blob/data URL output to disk (browser_save_blob)

Next:

• rebrowser-playwright backend
• codegen sessions
• coordinate-based (vision) clicks
• tracing / video recording