Browser Use

Browser Use

Use this for browser tasks against the existing Chrome session.

Config repair details live in mcporter-config.md.

Route

1. If the Codex Chrome or Chrome [Internal] plugin is callable in the current session, use its bundled Chrome-control skill. 2. Otherwise use the mcporter chrome-devtools route below.

Bundled or installed on disk does not mean available; the plugin must be callable in the active session. Both routes must use the user's existing Chrome profile.

For the mcporter fallback, use this target:

mcporter call chrome-devtools.<tool>

Most login-heavy sites fail in isolated profiles because fresh sessions trigger captcha, device checks, or missing SSO/extension state. Strongly prefer the existing Chrome profile for any website that needs login.

Never use chrome-isolated, Playwright, Puppeteer, the Codex in-app browser, AppleScript, osascript, GUI scripting, or macOS open for browser control unless the user explicitly asks for an isolated/new browser.

Screenshot/live UI bugs require this existing-Chrome path. curl, source inspection, Worker smoke tests, or local Playwright are supporting proof only; do not treat them as equivalent when the user showed a rendered browser problem or the page may depend on login/profile state.

Check MCP

mcporter list chrome-devtools --schema
mcporter call chrome-devtools.list_pages --args '{}' --output text

list_pages must show the user's real open tabs. If it shows a blank/default isolated Chrome, stop and say reattach failed.

If the call appears to hang while Chrome shows an auth/attach/update prompt, handle the attach alert before falling back. Prefer Peekaboo to press an explicit Chrome Allow button when visible; otherwise wait for the human. Do not restart daemons or kill MCP processes just because the first output is slow.

Tested attach-prompt recovery:

PB="${PEEKABOO_BIN:-$HOME/bin/peekaboo}"
[ -x "$PB" ] || PB="$(command -v peekaboo)"
"$PB" permissions status --json
"$PB" see --app frontmost --path /tmp/chrome-attach.png --json --annotate
# If the UI shows Chrome "Allow remote debugging?", click only the visible Allow button.
"$PB" click --coords <allow_x>,<allow_y> --json
mcporter call chrome-devtools.list_pages --args '{}' --output text

Use coordinates from the current Peekaboo snapshot, not stale notes. Success means list_pages returns the user's real Chrome tabs.

Attach-alert rule: when the current snapshot clearly shows Chrome asking to allow DevTools/MCP/browser automation attachment, click the visible Allow button once, then rerun list_pages. If the button is not visible or the prompt is ambiguous, stop and ask; do not silently switch to Playwright/Puppeteer.

If list_pages fails with DevToolsActivePort, ask the user to restart Chrome or the DevTools bridge, then retry once:

mcporter daemon restart
mcporter call chrome-devtools.list_pages --args '{}' --output text

If it still fails, stop and say Chrome DevTools MCP is unavailable. Do not use AppleScript.

Avoid noisy recovery loops. Repeated MCP/browser restarts can trigger reconnect/login prompts and alerts. Try once, then pause and choose a quieter path.

Typical Flow

# pick the page id from list_pages
mcporter call chrome-devtools.select_page --args '{"pageId":9}' --output text

# inspect page
mcporter call chrome-devtools.take_snapshot --args '{}' --output text

# navigate selected page
mcporter call chrome-devtools.navigate_page --args '{"url":"https://example.com"}' --output text

# click an element uid from the latest snapshot
mcporter call chrome-devtools.click --args '{"uid":"1_38","includeSnapshot":true}' --output text

# type/fill
mcporter call chrome-devtools.fill --args '{"uid":"1_13","value":"text","includeSnapshot":true}' --output text

# run JS, keep secrets out of output
mcporter call chrome-devtools.evaluate_script --args '{"function":"() => document.title"}' --output json

Use take_snapshot before actions and use current uid values only. Avoid take_screenshot unless visual layout matters.

Live UI Proof

For screenshot regressions, deployed dashboard checks, or anything where the rendered browser is the bug:

mcporter call chrome-devtools.list_pages --args '{}' --output text
mcporter call chrome-devtools.select_page --args '{"pageId":9}' --output text
mcporter call chrome-devtools.navigate_page --args '{"url":"https://example.com"}' --output text
mcporter call chrome-devtools.take_snapshot --args '{}' --output text
mcporter call chrome-devtools.evaluate_script --args '{"function":"() => document.body.innerText"}' --output json

Use the existing logged-in/profile-bearing tab set. If browser automation is unavailable, report that as a verification gap instead of substituting isolated browser tooling.

Secret Handling

Never print tokens/passwords from page DOM, network logs, or inputs. For token checks, return shape only: present/absent, length, status code, account/org name.

mcporter Chrome Config

Use when Chrome DevTools MCP attaches to a blank/isolated browser, cannot see the user's real tabs, or errors around DevToolsActivePort.

Expected Setup

Home config owns the default:

mcporter config get chrome-devtools --json

Check the source.path in that output. If it points at a repo config/mcporter.json, project config is overriding home config. Either run from a neutral cwd such as $HOME for browser automation, or update the project override with --scope project too.

Expected entry:

{
  "command": "npx",
  "args": [
    "-y",
    "chrome-devtools-mcp",
    "--auto-connect",
    "--userDataDir",
    "/Users/steipete/Library/Application Support/Google/Chrome"
  ]
}

chrome-devtools means reattach to existing Chrome. chrome-isolated is the explicit fresh-session escape hatch.

Verify

mcporter call chrome-devtools.list_pages --args '{}' --output text

Pass: output lists the user's visible tabs.

Fail: output shows only about:blank, a single empty tab, or a page set that does not match Chrome.

Fix Default Config

mcporter config add chrome-isolated --scope home --command npx --arg -y --arg chrome-devtools-mcp --description "Chrome DevTools MCP - isolated browser for explicit fresh-session tests"
mcporter config add chrome-devtools --scope home --command npx --arg -y --arg chrome-devtools-mcp --arg --auto-connect --arg --userDataDir --arg "$HOME/Library/Application Support/Google/Chrome" --description "Chrome DevTools MCP - reattach existing Chrome profile"

If mcporter config get chrome-devtools --json reports a project source.path, repair that project override too:

mcporter config add chrome-devtools --scope project --command npx --arg -y --arg chrome-devtools-mcp --arg --auto-connect --arg --userDataDir --arg "$HOME/Library/Application Support/Google/Chrome" --description "Chrome DevTools MCP - reattach existing Chrome profile"

Then verify again:

mcporter call chrome-devtools.list_pages --args '{}' --output text

Recovery

If DevToolsActivePort or connection startup fails:

mcporter daemon restart
mcporter call chrome-devtools.list_pages --args '{}' --output text

Retry once. If still broken, ask the user to restart Chrome or the DevTools bridge. Do not switch to AppleScript, Playwright, Puppeteer, or chrome-isolated unless the user explicitly asks for a fresh browser.

Source Notes

mcporter loads config layers from:

• explicit --config or $MCPORTER_CONFIG
• first existing home config: ~/.mcporter/mcporter.json or .jsonc
• project config/mcporter.json

Avoid /tmp config files for Chrome. They bypass normal config discovery and make agents copy long commands that are easy to misuse.