# Browser MCP Integration

Browser MCP enables Claude to interact with web pages through browser automation, providing an alternative when WebFetch is blocked or insufficient.

## Setup

### Installation
```bash
# Add to Claude MCP servers (included in setupClaudeServers)
claude mcp add browsermcp -- npx @browsermcp/mcp@latest
```

### Browser Extension
1. Install Browser MCP Chrome extension from Chrome Web Store
2. Click the extension icon and select 'Connect' to establish connection

## Available Commands

### Navigation
- `mcp__browsermcp__browser_navigate` - Navigate to a URL
- `mcp__browsermcp__browser_go_back` - Go back to previous page
- `mcp__browsermcp__browser_go_forward` - Go forward to next page

### Page Interaction
- `mcp__browsermcp__browser_snapshot` - Capture accessibility snapshot for element references
- `mcp__browsermcp__browser_screenshot` - Take a screenshot of current page
- `mcp__browsermcp__browser_click` - Click on page elements (requires element ref from snapshot)
- `mcp__browsermcp__browser_hover` - Hover over elements
- `mcp__browsermcp__browser_type` - Type text into editable elements
- `mcp__browsermcp__browser_select_option` - Select dropdown options
- `mcp__browsermcp__browser_press_key` - Press keyboard keys (e.g., PageDown, Enter, etc.)
- `mcp__browsermcp__browser_wait` - Wait for specified time in seconds

### Debugging
- `mcp__browsermcp__browser_get_console_logs` - Get browser console logs

## Common Workflow

1. **Navigate** to a page with `browser_navigate`
2. **Take screenshot** with `browser_screenshot` to see the page
3. **Get element references** with `browser_snapshot` for interaction
4. **Interact** with elements using `browser_click`, `browser_type`, etc.
5. **Navigate content** using `browser_press_key` (PageDown, PageUp, etc.)

## Use Cases

### Alternative to WebFetch
Use Browser MCP when:
- WebFetch is blocked by domains or anti-scraping measures
- Sites require JavaScript rendering or user interaction
- Need to interact with dynamic content (SPAs, AJAX-loaded content)
- Want to capture visual information via screenshots
- Need to fill forms or click buttons programmatically

### Specific Applications
- **Reddit scraping**: Access blocked Reddit URLs that WebFetch cannot reach
- **Claude.ai content**: Extract conversation and artifact data
- **Dynamic sites**: Interact with JavaScript-heavy applications
- **Form automation**: Fill and submit web forms
- **Visual verification**: Take screenshots for debugging or documentation

## Configuration

Browser MCP is automatically configured through the `setupClaudeServers()` function in `/home/hassen/config/scripts/private/shell/ai.bash`:

```bash
# Browser MCP for browser automation
claude mcp add browsermcp -- npx @browsermcp/mcp@latest
```

## Limitations

- **Token limits**: Large pages may exceed 25000 token maximum
- **Site blocking**: Some sites may block automated access
- **Extension dependency**: Requires browser extension to be connected and active
- **Content size**: Page content must fit within response limits

## Troubleshooting

### Extension Issues
- Verify Chrome extension is installed and active
- Check extension permissions
- Restart browser if connection fails

### Connection Problems
- Confirm MCP server is running
- Check browser extension connection status
- Verify no firewall blocking local connections

### Site Access Issues
- Some sites may require login sessions
- Respect rate limiting policies
- Use proper wait conditions for dynamic content
- Update element selectors if site structure changes

## Integration with setupClaudeServers

Browser MCP is automatically included when running:
```bash
setupClaudeServers  # or the alias: cl
```

This ensures Browser MCP is available alongside other MCP servers for comprehensive web automation capabilities.