Claude Code Browser MCP Setup

Documentation for using the Chrome DevTools MCP server with Claude Code to enable browser automation and web interaction capabilities.

Overview

This setup allows Claude Code to interact with Chrome browser through the Model Context Protocol (MCP). The Chrome DevTools MCP server provides tools for:

• Page navigation and management
• Taking snapshots and screenshots of web pages
• Clicking, filling forms, and interacting with page elements
• Network request monitoring
• Performance analysis
• JavaScript execution in browser context

Installation

1. Install the Chrome DevTools MCP Server

npm install -g @modelcontextprotocol/server-chrome-devtools

Or using npx (no installation required):

npx @modelcontextprotocol/server-chrome-devtools

2. Configure Claude Code

Add the MCP server to your Claude Code configuration file at ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-chrome-devtools"
      ]
    }
  }
}

If you installed globally, you can use:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "mcp-server-chrome-devtools"
    }
  }
}

3. Launch Chrome with Remote Debugging

The MCP server connects to Chrome via the Chrome DevTools Protocol. You need to launch Chrome with remote debugging enabled:

macOS:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Linux:

google-chrome --remote-debugging-port=9222

Windows:

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

4. Restart Claude Code

After configuration, restart Claude Code to load the MCP server.

Available Tools

The Chrome DevTools MCP provides the following tools (all prefixed with mcp__chrome-devtools__):

Page Management

• list_pages - List all open browser tabs
• select_page - Select a specific tab by index
• new_page - Open a new tab with URL
• navigate_page - Navigate current tab to URL
• navigate_page_history - Go back/forward in history
• close_page - Close a tab
• resize_page - Resize browser window

Page Inspection

• take_snapshot - Get text snapshot of page with UIDs for elements
• take_screenshot - Capture screenshot of page or element
• evaluate_script - Execute JavaScript in page context

Interaction

• click - Click on an element (by UID from snapshot)
• fill - Type into input fields
• fill_form - Fill multiple form fields at once
• hover - Hover over an element
• drag - Drag and drop elements
• upload_file - Upload files through file inputs
• handle_dialog - Handle browser alerts/confirms/prompts

Network

• list_network_requests - Get all network requests since last navigation
• get_network_request - Get specific request details by URL
• emulate_network - Simulate network conditions (3G, 4G, offline)

Performance

• performance_start_trace - Start performance recording
• performance_stop_trace - Stop recording and get results
• performance_analyze_insight - Get detailed performance insights
• emulate_cpu - Throttle CPU for testing

Console

• list_console_messages - Get console logs, warnings, errors

Waiting

• wait_for - Wait for specific text to appear on page

Typical Workflow

1. List and select pages:

   list_pages → select_page(0)
   

2. Navigate to a URL:

   navigate_page("https://example.com")
   

3. Take a snapshot to see page structure:

   take_snapshot → Returns UIDs for all interactive elements
   

4. Interact with elements:

   click(uid="1_28")
   fill(uid="1_86", value="search term")
   

5. Monitor network activity:

   list_network_requests → See all API calls, resources loaded
   

Example Use Cases

1. Browsing Hacker News

1. navigate_page("https://news.ycombinator.com")
2. take_snapshot
3. Read headlines and decide what to click
4. click(uid_of_interesting_article)
5. take_snapshot to read the article

2. Posting to Twitter/X

1. navigate_page("https://x.com")
2. take_snapshot
3. fill(uid_of_tweet_box, "Your tweet content")
4. click(uid_of_post_button)

3. Automated Testing

1. navigate_page("http://localhost:3000")
2. take_screenshot for visual comparison
3. fill_form with test data
4. click submit button
5. wait_for("Success message")
6. list_console_messages to check for errors

4. Performance Analysis

1. performance_start_trace(reload=true, autoStop=true)
2. Wait for trace to complete
3. performance_analyze_insight("LCPBreakdown")
4. Get detailed Core Web Vitals data

Tips and Best Practices

1. Always take a snapshot first - Before interacting with a page, take a snapshot to see available elements and their UIDs.

2. Use specific UIDs - Each element has a unique UID in the snapshot. Always use these for reliable interaction.

3. Handle dynamic content - Use wait_for when waiting for content to load after navigation or interaction.

4. Network monitoring - Enable network monitoring before navigating to capture all requests.

5. Error handling - Check console messages with list_console_messages to debug issues.

6. Clean up - Close tabs you're done with using close_page to keep the browser manageable.

Troubleshooting

MCP server not connecting

• Ensure Chrome is running with --remote-debugging-port=9222
• Check that no other process is using port 9222
• Try restarting both Chrome and Claude Code

Elements not found

• Take a fresh snapshot before clicking - UIDs change when page updates
• Ensure page has fully loaded before taking snapshot
• Use wait_for for dynamic content

Timeouts

• Increase timeout parameter in navigation calls
• Check network conditions - use emulate_network to test
• Verify page is actually loading in Chrome

Security Notes

• The remote debugging port (9222) allows full browser control
• Only use on trusted networks
• Don't expose the debugging port to external networks
• Consider using a separate Chrome profile for automation

Additional Resources

• Chrome DevTools Protocol Documentation
• Model Context Protocol Specification
• Claude Code Documentation

Session Example

Here's a real example from our session:

1. Started by browsing Hacker News to find interesting articles
2. Found an article about formally verified code
3. Clicked through to read the full article
4. Navigated to Twitter/X
5. Composed and posted a tweet about the article with key insights

All of this was done through Claude Code using natural language commands, with the MCP server handling the browser automation behind the scenes.