chrometools-mcp

MCP server for Chrome automation using Puppeteer with persistent browser sessions.

Table of Contents

• Installation
• Usage
• Available Tools - 16 Tools Total
  • Core Tools - ping, openBrowser
  • Interaction Tools - click, type, scrollTo
  • Inspection Tools - getElement, getComputedCss, getBoxModel, screenshot
  • Advanced Tools - executeScript, getConsoleLogs, hover, setStyles, setViewport, getViewport, navigateTo
• Typical Workflow Example
• Tool Usage Tips
• Configuration
• WSL Setup Guide → Full WSL Guide
• Development
• Features
• Architecture

Installation

npx -y chrometools-mcp

Usage

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["-y", "chrometools-mcp"]
    }
  }
}

Available Tools

1. Core Tools

ping

Test MCP connection with a simple ping-pong response.

• Parameters: message (optional)
• Example: { "name": "ping", "arguments": { "message": "hello" } }
• Returns: pong: hello

openBrowser

Opens browser and navigates to URL. Browser stays open for further interactions.

• Parameters: url (required)
• Use case: First step before other tools
• Returns: Page title + confirmation

2. Interaction Tools

click

Click an element and capture result screenshot.

• Parameters:
  • selector (required): CSS selector
  • waitAfter (optional): Wait time in ms (default: 1500)
• Use case: Buttons, links, form submissions
• Returns: Confirmation text + screenshot

type

Type text into input fields with optional clearing and typing delay.

• Parameters:
  • selector (required): CSS selector
  • text (required): Text to type
  • delay (optional): Delay between keystrokes in ms
  • clearFirst (optional): Clear field first (default: true)
• Use case: Filling forms, search boxes, text inputs
• Returns: Confirmation text

scrollTo

Scroll page to bring element into view.

• Parameters:
  • selector (required): CSS selector
  • behavior (optional): "auto" or "smooth"
• Use case: Lazy loading, sticky elements, visibility checks
• Returns: Final scroll position

3. Inspection Tools

getElement

Get HTML markup of element (defaults to body if no selector).

• Parameters: selector (optional)
• Use case: Inspecting structure, debugging markup
• Returns: Complete outerHTML

getComputedCss

Get all computed CSS styles for an element.

• Parameters: selector (optional)
• Use case: Debugging layout, verifying styles
• Returns: JSON object with CSS properties

getBoxModel

Get precise dimensions, positioning, margins, padding, and borders.

• Parameters: selector (required)
• Use case: Pixel-perfect measurements, layout analysis
• Returns: Box model data + metrics

screenshot

Capture PNG screenshot of specific element.

• Parameters:
  • selector (required)
  • padding (optional): Padding in pixels
• Use case: Visual documentation, bug reports
• Returns: Base64 PNG image

4. Advanced Tools

executeScript

Execute arbitrary JavaScript in page context.

• Parameters:
  • script (required): JavaScript code
  • waitAfter (optional): Wait time in ms (default: 500)
• Use case: Complex interactions, custom manipulations
• Returns: Execution result + screenshot

getConsoleLogs

Retrieve browser console logs (log, warn, error, etc.).

• Parameters:
  • types (optional): Array of log types to filter
  • clear (optional): Clear logs after reading (default: false)
• Use case: Debugging JavaScript errors, tracking behavior
• Returns: Array of log entries with timestamps

hover

Simulate mouse hover over element.

• Parameters: selector (required)
• Use case: Testing hover effects, tooltips, dropdown menus
• Returns: Confirmation text

setStyles

Apply inline CSS styles to element for live editing.

• Parameters:
  • selector (required)
  • styles (required): Array of {name, value} pairs
• Use case: Testing design changes, rapid prototyping
• Returns: Applied styles confirmation

setViewport

Change viewport dimensions for responsive testing.

• Parameters:
  • width (required): 320-4000px
  • height (required): 200-3000px
  • deviceScaleFactor (optional): 0.5-3 (default: 1)
• Use case: Testing mobile, tablet, desktop layouts
• Returns: Actual viewport dimensions

getViewport

Get current viewport size and device pixel ratio.

• Parameters: None
• Use case: Checking current screen dimensions
• Returns: Viewport metrics (width, height, DPR)

navigateTo

Navigate to different URL while keeping browser instance.

• Parameters:
  • url (required)
  • waitUntil (optional): load event type
• Use case: Moving between pages in workflow
• Returns: New page title

Typical Workflow Example

// 1. Open page
openBrowser({ url: "https://example.com/form" })

// 2. Fill form
type({ selector: "input[name='email']", text: "user@example.com" })
type({ selector: "input[name='password']", text: "secret123" })

// 3. Submit
click({ selector: "button[type='submit']" })

// 4. Verify
getElement({ selector: ".success-message" })
screenshot({ selector: ".dashboard", padding: 20 })

Tool Usage Tips

Persistent Browser:

• Browser windows remain open after each command
• Manual interaction possible between AI requests
• All tools work with currently open page

Best Practices:

• Start with openBrowser to establish context
• Use screenshot to verify visual results
• Combine tools for complex workflows
• Tools use CDP (Chrome DevTools Protocol) for precision

Configuration

Basic Configuration (Linux, macOS, Windows)

Add the MCP server to your MCP client configuration file:

Claude Desktop (~/.claude/mcp_config.json or ~/AppData/Roaming/Claude/mcp_config.json on Windows):

{
  "mcpServers": {
    "chrometools": {
      "command": "npx",
      "args": ["-y", "chrometools-mcp"]
    }
  }
}

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "chrometools": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "chrometools-mcp"],
      "env": {}
    }
  }
}

GUI Mode vs Headless Mode

The MCP server runs Chrome with headless: false by default, which means:

• ✅ Browser windows are visible on your screen
• ✅ You can interact with pages between AI requests
• ✅ You can see what the automation is doing in real-time

Requirements for GUI Mode:

• Linux/macOS: X server (usually available by default)
• WSL (Windows Subsystem for Linux): Requires X server setup (see WSL Setup Guide below)
• Windows: No additional setup needed

Alternative: Headless Mode with Virtual Display (xvfb)

If you don't need to see the browser window, you can use xvfb (virtual X server):

{
  "mcpServers": {
    "chrometools": {
      "type": "stdio",
      "command": "xvfb-run",
      "args": ["-a", "npx", "-y", "chrometools-mcp"],
      "env": {}
    }
  }
}

This runs Chrome in GUI mode but on a virtual display (window is not visible).

WSL Setup Guide

If you're using Windows Subsystem for Linux (WSL), special configuration is required to display Chrome GUI windows.

📖 See the complete WSL Setup Guide: WSL_SETUP.md

The guide includes:

• Step-by-step VcXsrv installation and configuration
• MCP server configuration for WSL (3 different options)
• Testing and troubleshooting procedures
• Solutions for common issues
• All reference links and resources

Quick Summary for WSL Users:

1. Install VcXsrv on Windows (Download)
2. Enable "Disable access control" in VcXsrv settings ⚠️ (Critical!)
3. Configure MCP server with DISPLAY=<your-windows-ip>:0 environment variable
4. Fully restart your MCP client

For detailed instructions, see WSL_SETUP.md.

Development

# Install dependencies
npm install

# Run locally
npm start

# Test with MCP inspector
npx @modelcontextprotocol/inspector node index.js

Features

• 16 Powerful Tools: Complete toolkit for browser automation
  • Core: ping, openBrowser
  • Interaction: click, type, scrollTo
  • Inspection: getElement, getComputedCss, getBoxModel, screenshot
  • Advanced: executeScript, getConsoleLogs, hover, setStyles, setViewport, getViewport, navigateTo
• Console Log Capture: Automatic JavaScript console monitoring
• Persistent Browser Sessions: Browser tabs remain open between requests
• Visual Browser (GUI Mode): See automation in real-time
• Cross-platform: Works on Windows/WSL, Linux, macOS
• Simple Installation: One command with npx
• CDP Integration: Uses Chrome DevTools Protocol for precision
• AI-Friendly: Detailed descriptions optimized for AI agents
• Responsive Testing: Built-in viewport control for mobile/tablet/desktop

Architecture

• Uses Puppeteer for Chrome automation
• MCP Server SDK for protocol implementation
• Zod for schema validation
• Stdio transport for communication