chrome-debug-launch

name	chrome-debug-launch
description	Launch Chrome on macOS with remote debugging enabled (port 9222) so chrome-devtools-mcp can control the real browser. Use when debugging a Chrome extension, when the user wants MCP to attach to their real logged-in Chrome session, or when `list_pages`/`navigate_page` need to hit an already-running Chrome instead of a fresh MCP-spawned one.

Chrome Debug Launch (macOS)

Goal: get a local Chrome running with --remote-debugging-port=9222 so chrome-devtools-mcp can attach via browserUrl=http://localhost:9222.

This is especially useful for debugging a Chrome extension loaded from disk, because the extension's pages, service worker, and content scripts all become inspectable targets over CDP.

Important: enterprise-managed Chrome blocks default profile

On this machine Chrome is managed by aftership.com (verified via --enrollment-domain=aftership.com in process args). Chrome honors the --remote-debugging-port flag only on a non-default --user-data-dir. Passing the flag to the default profile silently does nothing — the process starts but port 9222 never binds.

Always use the dedicated debug profile on this machine. Do not try the "default profile" variant — it will waste a round-trip.

Steps

1. Fully quit existing Chrome

osascript -e 'quit app "Google Chrome"' ; sleep 1
pgrep -x "Google Chrome" || echo "clean"

Don't do this without asking the user — it nukes their open tabs. Typically ask them to run the one-liner themselves.

2. Launch Chrome with the dedicated debug profile

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/chrome-debug-profile" &

Or as a single quit-and-relaunch one-liner:

osascript -e 'quit app "Google Chrome"' ; sleep 1 ; \
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/chrome-debug-profile" &

3. Load the extension under development (first time only)

In the newly launched Chrome window:

1. chrome://extensions → Developer mode ON (top-right)
2. Load unpacked → /Users/ll.li/long_git/deephear/extension/dist/

The extension, logins, bookmarks, and open tabs all persist inside ~/chrome-debug-profile across relaunches. Next time, just rerun the launch command — nothing to re-install, nothing to re-login.

After npm run build in extension/, click the 🔄 refresh icon on the extension card, then reload the YouTube tab. The extension entry itself does not need re-adding.

4. Verify port 9222 is live

curl -s http://localhost:9222/json/version | head -20

A JSON response with webSocketDebuggerUrl means success. If it returns nothing, see troubleshooting.

To list all debuggable targets (pages, service workers, extension pages):

curl -s http://localhost:9222/json | python3 -m json.tool

5. Point chrome-devtools-mcp at this Chrome

MCP config:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browserUrl=http://localhost:9222"
      ]
    }
  }
}

Restart the MCP client after editing so it picks up the new URL.

Recommended shell alias

# ~/.zshrc
alias chrome-debug='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir="$HOME/chrome-debug-profile" &'

Troubleshooting

Diagnostic: does Chrome have the flag vs is the port bound?

# 1. Is the flag present in the running process?
ps aux | grep "Google Chrome" | grep -- "--remote-debugging-port" | head -1

# 2. Is port 9222 actually listening?
lsof -iTCP:9222 -sTCP:LISTEN
# or
netstat -an -p tcp | grep 9222

Both should return a line. If the flag is present but the port isn't listening → Chrome silently ignored the flag → enterprise policy / default profile issue → switch to the dedicated profile (step 2 above).

Symptom	Fix
curl: (7) Failed to connect to localhost port 9222	Chrome didn't bind the port. Confirm process has the flag; if yes, it's the managed-profile block — use dedicated --user-data-dir.
Flag present in ps but port not listening	Enterprise policy blocked it on the default profile. Use --user-data-dir="$HOME/chrome-debug-profile".
MCP tools still spawn a fresh Chrome	browserUrl not picked up. Restart the MCP client; check JSON config syntax.
Extension service worker not in /json target list	Open chrome://extensions, click the extension's "service worker" link to wake it, then re-list.
Want to reset the debug profile	rm -rf ~/chrome-debug-profile then relaunch.

Permission etiquette

• Never quit the user's Chrome without explicit approval — it kills their tabs and session state.
• When they have an active main Chrome open, prefer telling them to run the quit+relaunch one-liner themselves.
• The dedicated profile is side-by-side safe: the user can keep their main Chrome if they're willing to close it first (Chrome only allows one instance per profile but different profiles can coexist as separate --user-data-dir).