Tool Reference

This page is generated at build time from the Shade Browser MCP engine source.

Generated tool count: 42

Source: ../shade-browser-mcp/src/shade_browser_mcp/server.py

Navigation

browser_navigate

Navigate to a URL and (by default) surface the Brave window to the foreground.

async def browser_navigate(url: str, slot: int = -1, focus: bool = True) -> str

Parameters

• url (str): The URL to navigate to
• slot (int): CDP slot number 0-19 (default: uses BRAVE_CDP_SLOT env or 0)
• focus (bool): If True (default), raise the window to the foreground after navigating. Set False when you want a quiet background load - useful in multi-agent flows where you don't want to steal the user's active window.

browser_tabs

List all open browser tabs/pages.

async def browser_tabs(slot: int = -1) -> str

Parameters

• slot (int): CDP slot number 0-19

browser_navigate_back

Navigate back in browser history.

async def browser_navigate_back(slot: int = -1) -> str

Parameters

• slot (int): CDP slot number 0-19

browser_open_visible

One-shot: claim a slot, launch a VISIBLE Brave window, navigate to URL.

The friction-free entrypoint for AI-driven walkthroughs. Replaces the error-prone three-step ritual of claim_slot -> launch -> navigate, and handles the Plasma+Wayland DISPLAY/XAUTHORITY auto-detection that has historically led to silent invisible-window failures.

async def browser_open_visible(url: str, session_id: str = '', extension_path: str = '', disable_other_extensions: bool = True, profile_mode: str = '') -> str

Parameters

• url (str): The URL to open (passed to browser_navigate after launch).
• session_id (str): Optional human-readable owner tag. Defaults to this MCP process's _own_session_tag() (CLAUDE_SESSION_NAME or pid-<N>), which means subsequent same-process tool calls pass the ownership check without needing to thread session_id through.
• extension_path (str): Optional unpacked Chrome extension directory.
• disable_other_extensions (bool): Whether to disable all other extensions when extension_path is provided.
• profile_mode (str): Optional launcher profile mode: "persistent" or "isolated".

Interaction

browser_execute_steps

Execute a chain of browser actions in one MCP call.

Reduces round-trip token cost vs calling individual tools per step. Dispatches steps sequentially; stops on first error (browsers do not rollback).

v1 supported actions: - {"action": "navigate", "url": "..."} - {"action": "click", "ref": "css-selector"} - {"action": "type", "ref": "css-selector", "text": "..."} - {"action": "snapshot"} - {"action": "wait_for", "selector": "...", "timeout": 30000}

async def browser_execute_steps(steps: list[dict], slot: int = -1) -> str

Parameters

• steps (list[dict]): List of step dicts; each has an "action" key + action-specific params
• slot (int): CDP slot number 0-19 (default: uses BRAVE_CDP_SLOT env or 0)

browser_click

Click an element on the page.

async def browser_click(selector: str = '', text: str = '', index: int = 0, slot: int = -1) -> str

Parameters

• selector (str): CSS selector to click
• text (str): Find element by visible text content and click it
• index (int): If multiple matches, click the Nth one (0-indexed)
• slot (int): CDP slot number 0-19

browser_type

Type text into an input field.

async def browser_type(selector: str = '', text: str = '', value: str = '', clear_first: bool = True, press_enter: bool = False, slot: int = -1) -> str

Parameters

• selector (str): CSS selector of the input
• text (str): Find input by nearby label text
• value (str): The text to type
• clear_first (bool): Clear the field before typing (default: True)
• press_enter (bool): Press Enter after typing (default: False)
• slot (int): CDP slot number 0-19

browser_press_key

Press a keyboard key or key combination.

async def browser_press_key(key: str, slot: int = -1) -> str

Parameters

• key (str): Key to press (e.g., 'Enter', 'Tab', 'Escape', 'Control+a')
• slot (int): CDP slot number 0-19

browser_wait_for

Wait for an element to reach a specific state.

async def browser_wait_for(selector: str = '', state: str = 'visible', timeout: int = 10000, slot: int = -1) -> str

Parameters

• selector (str): CSS selector to wait for
• state (str): State to wait for ('visible', 'hidden', 'attached', 'detached')
• timeout (int): Max wait time in milliseconds (default: 10000)
• slot (int): CDP slot number 0-19

browser_fill_form

Fill multiple form fields at once.

async def browser_fill_form(fields: str, slot: int = -1) -> str

Parameters

• fields (str): JSON string of field mappings, e.g. '{"#email": "user@test.com", "#password": "secret"}'
• slot (int): CDP slot number 0-19

browser_select_option

Select an option from a <select> dropdown.

async def browser_select_option(selector: str, value: str = '', label: str = '', slot: int = -1) -> str

Parameters

• selector (str): CSS selector of the <select> element
• value (str): Option value attribute to select
• label (str): Option visible text to select (used if value is empty)
• slot (int): CDP slot number 0-19

browser_hover

Hover over an element.

async def browser_hover(selector: str, slot: int = -1) -> str

Parameters

• selector (str): CSS selector to hover over
• slot (int): CDP slot number 0-19

Observation

browser_snapshot

Capture the current page's accessibility tree (DOM snapshot).

async def browser_snapshot(slot: int = -1) -> str

Parameters

• slot (int): CDP slot number 0-19

browser_take_screenshot

Take a screenshot. Saves to evidence directory if label is provided.

async def browser_take_screenshot(full_page: bool = False, selector: str = '', label: str = '', slot: int = -1) -> str

Parameters

• full_page (bool): Capture the full scrollable page
• selector (str): CSS selector to screenshot a specific element
• label (str): Evidence label (saves to engagement evidence directory)
• slot (int): CDP slot number 0-19

browser_watch_screen

Watch a browser slot over time by capturing a frame every interval.

Periodic-screenshot recorder: a headless-safe analogue of Rosetta's rosetta_record_walkthrough. Captures one PNG frame every interval_seconds for duration_seconds, letting an agent or the harness "watch" what the page does by Reading the returned frame paths in order.

Frames are captured via Playwright page.screenshot() - the SAME path browser_take_screenshot uses - so this works for a headless Brave (no X11/ffmpeg required). Frames are written to a dedicated subdirectory under the engagement evidence dir as ordered PNGs (frame-0001.png, ...).

async def browser_watch_screen(slot: int = -1, duration_seconds: int = 20, interval_seconds: int = 2, label: str = '', url_contains: str = '') -> str

Parameters

• slot (int): CDP slot number 0-19 (default: uses BRAVE_CDP_SLOT env or 0).
• duration_seconds (int): Total wall-clock duration to watch (default 20, capped at 120).
• interval_seconds (int): Seconds between frames (default 2, min 1).
• label (str): Evidence subdir name. Sanitised; defaults to a timestamped watch-<ts> directory when empty.
• url_contains (str): If set, capture the open tab whose URL contains this substring; otherwise the active tab. Falls back to the active tab if no tab matches.

browser_network_requests

Get recent network requests (useful for debugging API calls).

async def browser_network_requests(url_pattern: str = '', slot: int = -1) -> str

Parameters

• url_pattern (str): Filter requests by URL substring (optional)
• slot (int): CDP slot number 0-19

browser_console_messages

Get recent console messages from the browser.

async def browser_console_messages(slot: int = -1) -> str

Parameters

• slot (int): CDP slot number 0-19

browser_leak_check

Check for IP, DNS, and WebRTC leaks. Run after every tunnel assignment.

async def browser_leak_check(slot: int = -1) -> str

Parameters

• slot (int): CDP slot number 0-19

Session

browser_load_cookies

Load cookies into the browser. Supports HttpOnly cookies.

async def browser_load_cookies(cookies: str, slot: int = -1) -> str

Parameters

• cookies (str): JSON array of cookie objects, e.g.: [{"name": "session", "value": "abc", "domain": ".example.com", "path": "/", "httpOnly": true, "secure": true}]
• slot (int): CDP slot number 0-19

browser_list_sessions

Inventory saved browser sessions with metadata and hygiene warnings.

async def browser_list_sessions() -> str

browser_import_cookies_from_profile

Import cookies from a LOCALLY-installed browser profile into a slot.

Reads the user's real Brave/Chromium profile Cookies SQLite DB, decrypts each value (cross-store: keyring "Safe Storage" secret OR the basic-store peanuts key, with the Chrome 130+/Brave 142+ 32-byte domain-hash handled), filters by domain, and injects the matching cookies into the given CDP slot via the SAME path as browser_load_cookies (HttpOnly supported). Linux-only for now.

The profile DB is copied (locked while the browser runs) and opened read-only, so the live browser is never touched.

SECURITY: decrypted cookie VALUES are NEVER logged or returned. The result contains only names, domains, and counts.

async def browser_import_cookies_from_profile(domains: str, slot: int = -1, browser: str = 'brave', profile: str = 'Default') -> str

Parameters

• domains (str): Substring/host filter. Comma-separated for multiple, e.g. "trello.com,atlassian.com". A cookie is kept when any filter is a substring of its host. Required (pass a filter - importing every cookie in a profile is intentionally not the default).
• slot (int): CDP slot number 0-19 (default per BRAVE_CDP_SLOT).
• browser (str): "brave" (default), "chrome", or "chromium".
• profile (str): Profile directory name (default "Default").

browser_save_session

Save browser session (cookies + localStorage) to a file.

async def browser_save_session(name: str, slot: int = -1) -> str

Parameters

• name (str): Session name (saved to ~/.cache/shade-sessions/{name}.json)
• slot (int): CDP slot number 0-19

browser_load_session

Load a saved session into the browser.

async def browser_load_session(name: str, slot: int = -1, drop_cookie_names: str = '') -> str

Parameters

• name (str): Session name (loads from ~/.cache/shade-sessions/{name}.json)
• slot (int): CDP slot number 0-19
• drop_cookie_names (str): Optional comma-separated cookie names to skip while restoring. Useful for clearance cookies like cf_clearance that are bound to IP/browser fingerprint and can poison an otherwise valid auth session when transplanted.

browser_prepare_chatgpt_session

Prepare and classify a ChatGPT browser session.

This tool verifies readiness instead of assuming loaded cookies are usable. It never attempts to solve or bypass CAPTCHA, Cloudflare, or human checks.

async def browser_prepare_chatgpt_session(session_name: str = '', slot: int = -1, save_session_name: str = '', drop_cookie_names: str = 'cf_clearance', save_verified_session: bool = True) -> str

Parameters

• session_name (str): Optional saved session to restore before verification.
• slot (int): CDP slot number 0-19.
• save_session_name (str): Optional session name to save after readiness is verified.
• drop_cookie_names (str): Comma-separated cookie names to skip during restore. Defaults to cf_clearance because Cloudflare clearance is not portable.
• save_verified_session (bool): Save/update the session only when readiness is ready.

browser_clone_session

Clone a saved session into multiple browser slots.

async def browser_clone_session(name: str, slots: str = '[]') -> str

Parameters

• name (str): Session name to clone
• slots (str): JSON array of slot numbers, e.g. "[1, 2, 3]"

Slots / Fleet

browser_claim_slot

Claim a free CDP slot via flock-protected cdp_slots.claim_slot().

Safe for concurrent callers - slots.json access is serialized by flock and dead-PID entries are auto-expired on read (no zombie lockout).

async def browser_claim_slot(session_id: str = '', extension_path: str = '', disable_other_extensions: bool = True, profile_mode: str = '') -> str

Parameters

• session_id (str): Optional human-readable owner tag. When omitted (or blank / "unknown"), defaults to this MCP server's own identity via _own_session_tag() so that subsequent tool calls from the same process pass ownership validation (#2).
• extension_path (str): Optional unpacked Chrome extension directory.
• disable_other_extensions (bool): Whether to disable all other extensions when extension_path is provided.
• profile_mode (str): Optional launcher profile mode: "persistent" or "isolated".

browser_release_slot

Release a CDP slot - removes the slots.json entry and SIGTERMs Brave.

async def browser_release_slot(slot: int) -> str

Parameters

• slot (int): Slot number 0-19 to release.

browser_list_slots

List all CDP slots with validated liveness (dead PIDs already expired).

Returns the parsed slots.json after cdp_slots._validate_slots() has run, so only genuinely-alive slots appear. Empty {slots: {}} if nothing claimed.

async def browser_list_slots() -> str

Stealth

browser_use_tunnel

Launch a browser slot through a Shade VPN tunnel.

async def browser_use_tunnel(tunnel_id: str = '', slot: int = -1) -> str

Parameters

• tunnel_id (str): Tunnel name (e.g. 'mvpn_81') or empty for random
• slot (int): Specific slot to use, or -1 for auto-assign free slot

browser_use_tor

Launch a browser slot through Tor for .onion browsing.

async def browser_use_tor(slot: int = -1) -> str

Parameters

• slot (int): Specific slot to use, or -1 for auto-assign free slot

browser_rotate_ip

Rotate to a new tunnel exit IP. Optionally preserves session state.

async def browser_rotate_ip(slot: int = -1, preserve_session: bool = True) -> str

Parameters

• slot (int): CDP slot number currently in use
• preserve_session (bool): Save and reload cookies/localStorage across rotation

browser_apply_personality

Apply or regenerate a stealth personality profile for a browser slot.

Each slot has a unique personality (user agent, viewport, timezone, locale, platform, languages) that overrides browser fingerprint properties to avoid detection. Personalities are auto-applied on first connect.

Call with no personality_name to view the current personality. Call with personality_name="regenerate" to randomize a new personality.

async def browser_apply_personality(slot: int = -1, personality_name: str = '') -> str

Parameters

• slot (int): CDP slot number 0-19 (default: uses BRAVE_CDP_SLOT env or 0)
• personality_name (str): "regenerate" to create a new random personality, or empty string to view the current one

Web3

browser_web3_monitor

Install window.ethereum monitoring. Logs all wallet RPC calls.

async def browser_web3_monitor(slot: int = -1) -> str

Parameters

• slot (int): CDP slot number 0-19

browser_inject_signer

Inject a minimal EIP-1193 wallet provider. No MetaMask needed.

async def browser_inject_signer(private_key: str, chain_id: int = 1, slot: int = -1) -> str

Parameters

• private_key (str): Hex private key (0x...)
• chain_id (int): Ethereum chain ID (1=mainnet, 137=polygon, etc.)
• slot (int): CDP slot number 0-19

Advanced / Other

browser_evaluate

Execute JavaScript in the browser and return the result.

async def browser_evaluate(script: str, slot: int = -1) -> str

Parameters

• script (str): JavaScript code to execute
• slot (int): CDP slot number 0-19

browser_resize

Resize the browser viewport.

async def browser_resize(width: int = 1280, height: int = 720, slot: int = -1) -> str

Parameters

• width (int): Viewport width in pixels (default: 1280)
• height (int): Viewport height in pixels (default: 720)
• slot (int): CDP slot number 0-19

browser_cdp_command

Execute a raw CDP command. For advanced scenarios (WebAuthn, ServiceWorker, Fetch).

async def browser_cdp_command(method: str, params: str = '{}', slot: int = -1) -> str

Parameters

• method (str): CDP method (e.g., 'WebAuthn.enable', 'Network.setCookies')
• params (str): JSON string of CDP parameters
• slot (int): CDP slot number 0-19

browser_network_intercept

Capture network requests with full request/response bodies.

async def browser_network_intercept(url_pattern: str = '', capture_body: bool = True, slot: int = -1) -> str

Parameters

• url_pattern (str): URL substring to filter (empty = capture all)
• capture_body (bool): Include request/response bodies
• slot (int): CDP slot number 0-19

browser_ws_monitor

Install WebSocket monitoring. Logs all WS frames via prototype patching.

async def browser_ws_monitor(slot: int = -1) -> str

Parameters

• slot (int): CDP slot number 0-19

browser_webauthn_bypass

Create a virtual WebAuthn authenticator via CDP. Bypasses most WebAuthn.

async def browser_webauthn_bypass(rp_id: str = '', slot: int = -1) -> str

Parameters

• rp_id (str): Relying party ID (e.g., 'example.com'). Empty = auto-detect.
• slot (int): CDP slot number 0-19

browser_passive_recon

Run passive reconnaissance against a domain. Zero trace on target. Queries CT logs, DNS history, cached Shodan data via browser.

async def browser_passive_recon(domain: str, slot: int = -1) -> str

Parameters

• domain (str): Target domain (e.g., 'example.com')
• slot (int): CDP slot number (recommend using a Tor-routed slot)

browser_perf_profile

Run a CDP performance profile for the specified duration.

async def browser_perf_profile(duration: int = 5, slot: int = -1) -> str

Parameters

• duration (int): Profiling duration in seconds (default: 5)
• slot (int): CDP slot number 0-19