Chrome Browser Automation

Two Integrations – When to Use Each

Decision Guide

Need to test/debug a public site?     → Chrome DevTools MCP
Need performance analysis?            → Chrome DevTools MCP
Need to access authenticated apps?    → Claude-in-Chrome (--chrome)
Need to record a demo GIF?            → Claude-in-Chrome (--chrome)
Need to interact with Google Docs?    → Claude-in-Chrome (--chrome)
Need device/network emulation?        → Chrome DevTools MCP

Claude-in-Chrome:

• Authenticated web app interaction (Google Docs, Gmail, Notion)
• Session recording as GIF
• Natural language element finding
• Form automation with your saved data
• Page text extraction
• Shortcut/workflow execution

Chrome DevTools MCP (Always Available)

No setup required – these tools work immediately.

Step 1: List and Select Pages

// List all open pages
mcp__chrome - devtools__list_pages();

// Select a page to work with
mcp__chrome - devtools__select_page({ pageId: 1 });

// Create a new page
mcp__chrome - devtools__new_page({ url: 'https://example.com' });

Step 2: Navigate and Interact

// Navigate to URL
mcp__chrome - devtools__navigate_page({ url: 'https://example.com' });

// Take accessibility snapshot (get element UIDs)
mcp__chrome - devtools__take_snapshot();

// Click element by UID from snapshot
mcp__chrome - devtools__click({ uid: 'ref_123' });

// Fill form field
mcp__chrome - devtools__fill({ uid: 'ref_456', value: 'test@example.com' });

// Fill entire form
mcp__chrome -
  devtools__fill_form({
    elements: [
      { uid: 'ref_456', value: 'test@example.com' },
      { uid: 'ref_789', value: 'password123' },
    ],
  });

Step 3: Debug and Inspect

// Read console messages
mcp__chrome - devtools__list_console_messages({ types: ['error', 'warn'] });

// Get specific console message details
mcp__chrome - devtools__get_console_message({ msgid: 1 });

// List network requests
mcp__chrome - devtools__list_network_requests({ resourceTypes: ['xhr', 'fetch'] });

// Get request/response details
mcp__chrome - devtools__get_network_request({ reqid: 1 });

// Execute JavaScript
mcp__chrome -
  devtools__evaluate_script({
    function: '() => document.title',
  });

Step 4: Performance Analysis

// Start performance trace (with page reload)
mcp__chrome - devtools__performance_start_trace({ reload: true, autoStop: true });

// Or manual stop
mcp__chrome - devtools__performance_start_trace({ reload: true, autoStop: false });
// ... interact with page ...
mcp__chrome - devtools__performance_stop_trace();

// Analyze specific insight
mcp__chrome -
  devtools__performance_analyze_insight({
    insightSetId: 'navigation-1',
    insightName: 'LCPBreakdown',
  });

Step 5: Device Emulation

// Emulate mobile device
mcp__chrome -
  devtools__emulate({
    viewport: {
      width: 375,
      height: 667,
      deviceScaleFactor: 2,
      isMobile: true,
      hasTouch: true,
    },
    userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X)...',
  });

// Emulate slow network
mcp__chrome - devtools__emulate({ networkConditions: 'Slow 3G' });

// Emulate geolocation
mcp__chrome -
  devtools__emulate({
    geolocation: { latitude: 37.7749, longitude: -122.4194 },
  });

Claude-in-Chrome (Requires Setup)

Prerequisites

1. Install Claude-in-Chrome extension (v1.0.36+) from Chrome Web Store
2. Start Claude with flag: claude --chrome
3. Chrome must be visible (no headless mode)
4. Paid Claude plan required (Pro, Team, or Enterprise)

Step 1: Get Tab Context

// ALWAYS call first to get available tabs
mcp__claude-in-chrome__tabs_context_mcp({ createIfEmpty: true })

// Create a new tab for this conversation
mcp__claude-in-chrome__tabs_create_mcp()

Step 2: Navigate and Read

// Navigate to URL
mcp__claude-in-chrome__navigate({ url: "https://docs.google.com", tabId: 123 })

// Read page structure (accessibility tree)
mcp__claude-in-chrome__read_page({ tabId: 123 })

// Find elements by natural language
mcp__claude-in-chrome__find({ query: "login button", tabId: 123 })

// Extract page text
mcp__claude-in-chrome__get_page_text({ tabId: 123 })

Step 3: Interact

// Click, type, screenshot via computer tool
mcp__claude-in-chrome__computer({
  action: "left_click",
  coordinate: [100, 200],
  tabId: 123
})

mcp__claude-in-chrome__computer({
  action: "type",
  text: "Hello world",
  tabId: 123
})

mcp__claude-in-chrome__computer({
  action: "screenshot",
  tabId: 123
})

// Fill form by element reference
mcp__claude-in-chrome__form_input({
  ref: "ref_1",
  value: "test@example.com",
  tabId: 123
})

Step 4: Record GIF Demo

// Start recording
mcp__claude-in-chrome__gif_creator({ action: "start_recording", tabId: 123 })

// Take screenshot to capture initial state
mcp__claude-in-chrome__computer({ action: "screenshot", tabId: 123 })

// ... perform actions ...

// Take final screenshot
mcp__claude-in-chrome__computer({ action: "screenshot", tabId: 123 })

// Stop and export
mcp__claude-in-chrome__gif_creator({ action: "stop_recording", tabId: 123 })
mcp__claude-in-chrome__gif_creator({
  action: "export",
  download: true,
  filename: "demo.gif",
  tabId: 123
})

</execution_process>

<best_practices>

Chrome DevTools MCP

1. Always take snapshot first to get element UIDs before clicking/filling
2. Use includeSnapshot: true on actions to get updated state
3. Filter network requests by resourceTypes to avoid noise
4. Save traces to file with filePath parameter for later analysis

Claude-in-Chrome

1. Call tabs_context_mcp first to get valid tab IDs
2. Create new tabs rather than reusing existing ones
3. Use read_page before find to understand page structure
4. Filter console with patterns to avoid verbosity
5. Dismiss modal dialogs manually – they block all events

General

1. Prefer Chrome DevTools MCP for public sites (always available)
2. Use Claude-in-Chrome only when authentication is required
3. Don’t trigger alert/confirm/prompt – they block browser events

</best_practices>

// Create page and navigate
mcp__chrome - devtools__new_page({ url: 'https://example.com/login' });

// Take snapshot to get element UIDs
mcp__chrome - devtools__take_snapshot();

// Fill login form
mcp__chrome -
  devtools__fill_form({
    elements: [
      { uid: 'email_field', value: 'test@example.com' },
      { uid: 'password_field', value: 'testpass123' },
    ],
  });

// Click submit
mcp__chrome - devtools__click({ uid: 'submit_button' });

// Check for errors
mcp__chrome - devtools__list_console_messages({ types: ['error'] });

</usage_example>

<usage_example> Performance Audit (Chrome DevTools MCP):

// Navigate to page
mcp__chrome - devtools__navigate_page({ url: 'https://example.com' });

// Run performance trace with reload
mcp__chrome -
  devtools__performance_start_trace({
    reload: true,
    autoStop: true,
    filePath: 'trace.json.gz',
  });

// Analyze LCP breakdown
mcp__chrome -
  devtools__performance_analyze_insight({
    insightSetId: 'navigation-1',
    insightName: 'LCPBreakdown',
  });

</usage_example>

<usage_example> Google Docs Editing (Claude-in-Chrome):

// Get tab context
mcp__claude-in-chrome__tabs_context_mcp({ createIfEmpty: true })

// Navigate to Google Docs (uses your login)
mcp__claude-in-chrome__navigate({
  url: "https://docs.google.com/document/d/YOUR_DOC_ID",
  tabId: 123
})

// Read page to find elements
mcp__claude-in-chrome__read_page({ tabId: 123 })

// Click in document and type
mcp__claude-in-chrome__computer({
  action: "left_click",
  ref: "document_body",
  tabId: 123
})

mcp__claude-in-chrome__computer({
  action: "type",
  text: "Meeting notes for today...",
  tabId: 123
})

</usage_example>

<usage_example> Record Demo GIF (Claude-in-Chrome):

// Start recording
mcp__claude-in-chrome__gif_creator({ action: "start_recording", tabId: 123 })

// Initial screenshot
mcp__claude-in-chrome__computer({ action: "screenshot", tabId: 123 })

// Navigate
mcp__claude-in-chrome__navigate({ url: "https://example.com/product", tabId: 123 })
mcp__claude-in-chrome__computer({ action: "screenshot", tabId: 123 })

// Click add to cart
mcp__claude-in-chrome__computer({ action: "left_click", ref: "add_to_cart", tabId: 123 })
mcp__claude-in-chrome__computer({ action: "screenshot", tabId: 123 })

// Stop and export
mcp__claude-in-chrome__gif_creator({ action: "stop_recording", tabId: 123 })
mcp__claude-in-chrome__gif_creator({
  action: "export",
  download: true,
  filename: "add-to-cart-flow.gif",
  options: { showClickIndicators: true, showProgressBar: true },
  tabId: 123
})

</usage_example>

Available Tools

Chrome DevTools MCP (Always Available)

Claude-in-Chrome (Requires --chrome flag)

Agent Integration

This skill is automatically assigned to:

• developer – Testing, debugging, data extraction
• qa – Automated testing, form validation, user flow verification
• security-architect – Security testing, authentication flows
• devops-troubleshooter – Production debugging, monitoring
• researcher – Web scraping, data extraction

Related Workflow

For guidance on using this skill effectively, see the corresponding workflow:

• Workflow File: .claude/workflows/chrome-browser-skill-workflow.md
• When to Use: When you need browser automation for testing, debugging, authenticated workflows, or demo recording
• Integration Methods:
  • Slash command invocation (/chrome-browser)
  • Agent skill assignment (via frontmatter)
  • Direct script execution

Two Integration Options:

• Chrome DevTools MCP (always available) – For public site testing, performance analysis, debugging
• Claude-in-Chrome (requires --chrome flag) – For authenticated app workflows, GIF recording

The workflow provides examples for invocation methods, agent assignment, and memory integration patterns.

Troubleshooting

Claude-in-Chrome “Browser extension is not connected”

Symptom: When using --chrome flag, tools return “Browser extension is not connected” error despite extension being installed.

Root Cause: Claude.app (desktop) and Claude Code register competing native messaging hosts. When both are installed, the Chrome extension connects to whichever registered last, causing connection failures.

Diagnosis:

1. Check if both Claude.app and Claude Code are installed
2. On Windows: Check %APPDATA%\Claude\ChromeNativeHost\com.anthropic.claude_browser_extension.json
3. On macOS: Check ~/Library/Application Support/Claude/ChromeNativeHost/

Known Bug: This is documented in GitHub issues:

• #15336 – Windows Native Messaging Host not installing
• #14894 – Reconnect extension fails on macOS
• #20790 – Extension connects to Claude.app instead of Claude Code

Workaround (macOS):

# Disable Claude.app's native host (keep file for restoration)
cd ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/
mv com.anthropic.claude_browser_extension.json com.anthropic.claude_browser_extension.json.disabled

# Restart Chrome completely (quit and reopen)
# Then start Claude Code with --chrome flag

Workaround (Windows): Not fully documented. Potential approach:

# Rename the config to disable Claude.app's registration
cd $env:APPDATA\Claude\ChromeNativeHost
ren com.anthropic.claude_browser_extension.json com.anthropic.claude_browser_extension.json.disabled

# Restart Chrome and try again

Alternative: Use Chrome DevTools MCP instead – it works without the extension and provides similar functionality for most use cases.

Modal Dialogs Blocking Events

Symptom: After triggering alert/confirm/prompt, all browser tools stop responding.

Cause: JavaScript modal dialogs block all browser events including extension communication.

Fix: User must manually dismiss the dialog in the browser. Avoid triggering dialogs in automation scripts.

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: Your context may reset. If it’s not in memory, it didn’t happen.