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

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

Installation

Clone or download this repository
Navigate to the project directory:

   cd mcp_chrome

Create a virtual environment (recommended):

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

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

Activate your virtual environment (if using one)
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: ``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

Chromium download failed: Ensure you have internet access for the initial Chromium download
Permission denied: Make sure you have write permissions in the current directory for screenshots
Element not found: Verify your CSS selectors or XPath expressions are correct
Browser crashes: Check if Chrome/Chromium is already running and close other instances
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:

Use custom screenshot directory:

   export CHROME_SCREENSHOT_DIR="/Users/username/Pictures/screenshots"

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

Check directory permissions:

   ls -la /current/directory

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:

Close all Chrome windows and try again
Use headless mode: export CHROME_HEADLESS=true
Check for running Chrome instances: The server will warn you if Chrome is already running

macOS-specific solutions:

System Preferences > Security & Privacy: Check if Chrome is blocked
Quit Chrome completely from Activity Monitor
Restart Chrome and try again

Advanced troubleshooting:

Custom Chrome path: export CHROME_EXECUTABLE_PATH="/path/to/chrome"
Force headless mode in your MCP configuration
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.

chrome_mcp_server