# 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

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

Or using npx (no installation required):
```bash
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`:

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

If you installed globally, you can use:
```json
{
  "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:**
```bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
```

**Linux:**
```bash
google-chrome --remote-debugging-port=9222
```

**Windows:**
```bash
"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](https://chromedevtools.github.io/devtools-protocol/)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Code Documentation](https://docs.anthropic.com/claude/docs/claude-code)

## 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.