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:

   cd mcp_chrome
   

3. Create a virtual environment (recommended):

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

4. Install dependencies:

   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:

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

   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

{
  "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

# 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

# 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

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

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:

export CHROME_HEADLESS=true
python chrome_mcp_server.py

Closing the Browser

Always close the browser when you're done:

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:

   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:

   ls -la /current/directory
   

4. Use absolute paths in your screenshot calls:

   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:

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.