Chrome Tools MCP Server

An MCP server that provides tools for interacting with Chrome through its DevTools Protocol. This server enables remote control of Chrome tabs, including executing JavaScript, capturing screenshots, monitoring network traffic, and more.

Why use an MCP server like this?

This type of MCP Server is useful When you need to manually configure your browser to be in a certain state before you let an AI tool like Cline poke at it. You can also use this tool to listen to and pull network events into its context.

Features

• List Chrome tabs
• Execute JavaScript in tabs
• Capture screenshots
• Monitor network traffic
• Navigate tabs to URLs
• Query DOM elements
• Click elements with console output capture

Installation

npm install @nicholmikey/chrome-tools

Configuration

The server can be configured through environment variables in your MCP settings:

{
  "chrome-tools": {
    "command": "node",
    "args": ["path/to/chrome-tools/dist/index.js"],
    "env": {
      "CHROME_DEBUG_URL": "http://localhost:9222",
      "CHROME_CONNECTION_TYPE": "direct",
      "CHROME_ERROR_HELP": "custom error message"
    }
  }
}

Environment Variables

• CHROME_DEBUG_URL: The URL where Chrome's remote debugging interface is available (default: http://localhost:9222)
• CHROME_CONNECTION_TYPE: Connection type identifier for logging (e.g., "direct", "ssh-tunnel", "docker")
• CHROME_ERROR_HELP: Custom error message shown when connection fails

Setup Guide

Native Setup (Windows/Mac/Linux)

1. Launch Chrome with remote debugging enabled:

   # Windows
   "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
   
   # Mac
   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
   
   # Linux
   google-chrome --remote-debugging-port=9222

2. Configure MCP settings:

   {
     "env": {
       "CHROME_DEBUG_URL": "http://localhost:9222",
       "CHROME_CONNECTION_TYPE": "direct"
     }
   }

WSL Setup

When running in WSL, you'll need to set up an SSH tunnel to connect to Chrome running on Windows:

1. Launch Chrome on Windows with remote debugging enabled
2. Create an SSH tunnel:

   ssh -N -L 9222:localhost:9222 windowsuser@host

3. Configure MCP settings:

   {
     "env": {
       "CHROME_DEBUG_URL": "http://localhost:9222",
       "CHROME_CONNECTION_TYPE": "ssh-tunnel",
       "CHROME_ERROR_HELP": "Make sure the SSH tunnel is running: ssh -N -L 9222:localhost:9222 windowsuser@host"
     }
   }

Docker Setup

When running Chrome in Docker:

1. Launch Chrome container:

   docker run -d --name chrome -p 9222:9222 chromedp/headless-shell

2. Configure MCP settings:

   {
     "env": {
       "CHROME_DEBUG_URL": "http://localhost:9222",
       "CHROME_CONNECTION_TYPE": "docker"
     }
   }

Tools

list_tabs

Lists all available Chrome tabs.

execute_script

Executes JavaScript code in a specified tab. Parameters:

• tabId: ID of the Chrome tab
• script: JavaScript code to execute

capture_screenshot

Captures a screenshot of a specified tab, automatically optimizing it for AI model consumption. Parameters:

• tabId: ID of the Chrome tab
• format: Image format (jpeg/png) - Note: This is only for initial capture. Final output uses WebP with PNG fallback
• quality: JPEG quality (1-100) - Note: For initial capture only
• fullPage: Capture full scrollable page

Image Processing:

1. WebP Optimization (Primary Format):
   • First attempt: WebP with quality 80 and high compression effort
   • Second attempt: WebP with quality 60 and near-lossless compression if first attempt exceeds 1MB
2. PNG Fallback:
   • Only used if WebP processing fails
   • Includes maximum compression and color palette optimization
3. Size Constraints:
   • Maximum dimensions: 900x600 (maintains aspect ratio)
   • Maximum file size: 1MB
   • Progressive size reduction if needed

capture_network_events

Monitors and captures network events from a specified tab. Parameters:

• tabId: ID of the Chrome tab
• duration: Duration in seconds to capture
• filters: Optional type and URL pattern filters

load_url

Navigates a tab to a specified URL. Parameters:

• tabId: ID of the Chrome tab
• url: URL to load

query_dom_elements

Queries and retrieves detailed information about DOM elements matching a CSS selector. Parameters:

• tabId: ID of the Chrome tab
• selector: CSS selector to find elements Returns:
• Array of DOM elements with properties including:
  • nodeId: Unique identifier for the node
  • tagName: HTML tag name
  • textContent: Text content of the element
  • attributes: Object containing all element attributes
  • boundingBox: Position and dimensions of the element
  • isVisible: Whether the element is visible
  • ariaAttributes: ARIA attributes for accessibility

click_element

Clicks on a DOM element and captures any console output triggered by the click. Parameters:

• tabId: ID of the Chrome tab
• selector: CSS selector to find the element to click Returns:
• Object containing:
  • message: Success/failure message
  • consoleOutput: Array of console messages triggered by the click

License

MIT