Chrome DevTools MCP

The container includes a pre-configured Chrome DevTools MCP server that gives Claude Code headless browser automation capabilities. Navigate web pages, take screenshots, inspect the DOM, and interact with page elements — no additional setup needed.

How It Works

The entrypoint launches a persistent headless Chrome with remote debugging on port 9222. The chrome-devtools-mcp MCP server is registered in Claude Code settings and connects to this shared browser via --browserUrl. All sessions share a single browser instance and cookie jar — logins, cookies, and authentication persist across projects.

Available Tools

Tool	Description
navigate_page	Navigate to a URL and wait for the page to load
take_screenshot	Capture a PNG screenshot of the current page
take_snapshot	Get an accessibility tree snapshot of the page
click	Click an element on the page
type	Type text into an input field
hover	Hover over an element
scroll	Scroll the page or a specific element
evaluate	Execute JavaScript in the page context
get_console_logs	Retrieve console log messages
get_page_info	Get page metadata (title, URL, etc.)

Architecture

The browser stack uses four components that work together:

1. Playwright Chromium — ARM64-compatible Chromium binary installed at build time via npx playwright install --with-deps chromium
2. Chrome symlink — bridges Puppeteer’s expected path (/opt/google/chrome/chrome) to the Playwright binary
3. Shared Chrome process — launched by chrome-browser.sh with --remote-debugging-port=9222, auto-restarts on crash
4. Global MCP registration — settings.json registers chrome-devtools-mcp with --browserUrl=http://localhost:9222

Google Chrome has no ARM64 .deb package, and Ubuntu 24.04’s chromium-browser apt package redirects to snap (which doesn’t work in containers). Playwright’s bundled Chromium is the only reliable option for ARM64 containers.

Verification

Confirm the setup works inside the container:

# Chrome binary responds
/opt/google/chrome/chrome --version

# Symlink is correct
ls -la /opt/google/chrome/chrome

# Remote debugging is active
curl http://localhost:9222/json/version

# Self-test includes Chrome checks
claude-self-test

Headed Mode (VNC)

When ENABLE_VNC=true, the entrypoint starts the VNC stack before launching Chrome. The chrome-browser.sh script detects that DISPLAY is set and runs Chrome in headed mode on the virtual display, so you can see the browser in the VNC viewer.

Open http://localhost:6080/vnc.html to see the virtual display. See Remote Display (noVNC) for details.

Troubleshooting

See Troubleshooting — Chrome DevTools MCP for solutions to common issues including remote debugging failures, profile lock errors, and duplicate MCP tools.