# Chrome MCP Server

A Model Context Protocol (MCP) server for controlling and automating Google Chrome browser operations using Puppeteer. This server provides tools for web automation, element interaction, and browser management.

## Features

The Chrome MCP server provides the following tools:

- **open_url**: Navigate to a specific URL
- **get_page_title**: Get the current page title
- **get_page_url**: Get the current page URL
- **click_element**: Click on elements using CSS selectors or XPath
- **type_text**: Type text into input fields
- **screenshot**: Take screenshots of the current page
- **scroll_page**: Scroll the page in any direction
- **wait_for_element**: Wait for elements to appear on the page
- **close_browser**: Close the Chrome browser

## Prerequisites

1. **Python 3.8+** installed on your system
2. **Google Chrome** browser installed (recommended) or let Puppeteer download Chromium automatically

## Installation

1. Clone or download this repository
2. Navigate to the project directory:
   ```bash
   cd mcp_chrome
   ```

3. Create a virtual environment (recommended):
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

4. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

## Configuration

### Environment Variables

You can configure the Chrome MCP server using environment variables:

- `CHROME_HEADLESS`: Set to `true` to run Chrome in headless mode (default: `false`)
- `CHROME_EXECUTABLE_PATH`: Specify a custom path to your Chrome executable (optional)
- `CHROME_SCREENSHOT_DIR`: Specify a custom directory for saving screenshots (optional)

Examples:
```bash
# Run in headless mode
export CHROME_HEADLESS=true

# Use custom Chrome path
export CHROME_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

# Use custom screenshot directory
export CHROME_SCREENSHOT_DIR="/Users/username/Pictures/screenshots"
```

## Usage

### Running the Server

1. Activate your virtual environment (if using one)
2. Run the server:
   ```bash
   python chrome_mcp_server.py
   ```

The server will start and listen for MCP client connections via stdio.

### Integration with MCP Clients

This server can be integrated with any MCP-compatible client. Configure your client to use the Chrome MCP server by specifying the path to `chrome_mcp_server.py`.

### Example MCP Client Configuration

```json
{
  "mcpServers": {
    "chrome": {
      "command": "python",
      "args": ["/path/to/chrome_mcp_server.py"],
      "env": {
        "CHROME_HEADLESS": "false"
      }
    }
  }
}
```
### Cursor Integration

To enable the Chrome MCP server in Cursor, add the following configuration to `~/.cursor/mcp.json`:

## Tool Examples

### Basic Navigation
```python
# Open a website
await client.call_tool("open_url", {"url": "https://example.com"})

# Get page information
title = await client.call_tool("get_page_title", {})
current_url = await client.call_tool("get_page_url", {})
```

### Element Interaction
```python
# Click on a button
await client.call_tool("click_element", {
    "selector": "#submit-button",
    "selector_type": "css"
})

# Type text into a search box
await client.call_tool("type_text", {
    "selector": "input[name='q']",
    "text": "search query",
    "clear_first": True
})
```

### Page Manipulation
```python
# Take a screenshot
await client.call_tool("screenshot", {"filename": "page.png"})

# Scroll down the page
await client.call_tool("scroll_page", {
    "direction": "down",
    "pixels": 1000
})

# Wait for an element to appear
await client.call_tool("wait_for_element", {
    "selector": ".loading-spinner",
    "timeout": 30
})
```

## Browser Management

### Using Local Chrome vs Downloaded Chromium

The server automatically detects and uses your locally installed Google Chrome browser. If Chrome is not found, it falls back to downloading and using Chromium.

**To use your local Chrome:**
- The server automatically searches for Chrome in common installation paths
- No additional configuration needed

**To specify a custom Chrome path:**
```bash
export CHROME_EXECUTABLE_PATH="/path/to/your/chrome"
```

**To force using downloaded Chromium:**
- Simply don't install Chrome, or remove the Chrome executable from the detected paths

### Headless Mode
For server environments or automated testing, you can run Chrome in headless mode:
```bash
export CHROME_HEADLESS=true
python chrome_mcp_server.py
```

### Closing the Browser
Always close the browser when you're done:
```python
await client.call_tool("close_browser", {})
```

## Error Handling

The server includes comprehensive error handling:
- WebDriver initialization errors
- Element not found errors
- Timeout errors
- General WebDriver exceptions

All errors are returned as text content with descriptive error messages.

## Security Considerations

- The server runs Chromium with reduced security options for automation purposes
- Be cautious when automating websites that contain sensitive information
- Consider using headless mode in production environments
- The server automatically closes the browser on exit to prevent resource leaks
- Puppeteer automatically downloads and manages the appropriate Chromium version

## Troubleshooting

### Common Issues

1. **Chromium download failed**: Ensure you have internet access for the initial Chromium download
2. **Permission denied**: Make sure you have write permissions in the current directory for screenshots
3. **Element not found**: Verify your CSS selectors or XPath expressions are correct
4. **Browser crashes**: Check if Chrome/Chromium is already running and close other instances
5. **First run delay**: The first run may take longer as Puppeteer downloads Chromium

### Screenshot Issues

**"Read-only file system" error:**
This happens when the current directory doesn't have write permissions. Solutions:

1. **Use custom screenshot directory:**
   ```bash
   export CHROME_SCREENSHOT_DIR="/Users/username/Pictures/screenshots"
   ```

2. **The server automatically falls back to `/tmp` directory** if the current directory is read-only

3. **Check directory permissions:**
   ```bash
   ls -la /current/directory
   ```

4. **Use absolute paths** in your screenshot calls:
   ```python
   await client.call_tool("screenshot", {"filename": "/Users/username/screenshot.png"})
   ```

### "Browser closed unexpectedly" Error

This error commonly occurs on macOS due to security restrictions. Here are solutions:

**Immediate fixes:**
1. **Close all Chrome windows** and try again
2. **Use headless mode**: `export CHROME_HEADLESS=true`
3. **Check for running Chrome instances**: The server will warn you if Chrome is already running

**macOS-specific solutions:**
1. **System Preferences > Security & Privacy**: Check if Chrome is blocked
2. **Quit Chrome completely** from Activity Monitor
3. **Restart Chrome** and try again

**Advanced troubleshooting:**
1. **Custom Chrome path**: `export CHROME_EXECUTABLE_PATH="/path/to/chrome"`
2. **Force headless mode** in your MCP configuration
3. **Check Chrome's debugging output** (the server now shows this by default)

### Debug Mode

For debugging, you can run the server with verbose output:
```bash
python -u chrome_mcp_server.py
```

## Contributing

Feel free to submit issues, feature requests, or pull requests to improve the Chrome MCP server.

## License

This project is open source and available under the MIT License.