Skip to content

USAGE.md

Latest commit

 

History

History
528 lines (343 loc) · 11.8 KB

USAGE.md

File metadata and controls

528 lines (343 loc) · 11.8 KB
Raw

Detailed Usage Guide

This guide provides comprehensive instructions for setting up and using chrome-devtools-mcp on Windows with various AI coding assistants.

Table of Contents

Installation Steps

1. Install Node.js and npm

Download and install Node.js LTS version from https://nodejs.org/

Verify installation:

node --version
npm --version

You should see version numbers (Node.js 16.x or higher recommended).

2. Install chrome-devtools-mcp

Install globally so it's available from any directory:

npm install -g chrome-devtools-mcp

Alternatively, use npx to run without global installation:

npx chrome-devtools-mcp --version

3. Verify Chrome Installation

Ensure Google Chrome is installed at the default location:

C:\Program Files\Google\Chrome\Application\chrome.exe

If Chrome is installed elsewhere, you will need to update the paths in the PowerShell scripts.

Configuration for Different IDEs

Codex IDE

Codex uses a TOML configuration file located at:

%USERPROFILE%\.codex\config.toml

To configure:

  1. Copy one of the example files from this repository:
Copy-Item .\examples\config.headful.toml $env:USERPROFILE\.codex\config.toml
  1. Edit the file and replace <YOUR_USER> with your Windows username:
notepad $env:USERPROFILE\.codex\config.toml
  1. Save and restart Codex IDE.

Cursor IDE

Cursor also supports MCP configuration. To set up:

  1. Open Cursor Settings (Ctrl+,)
  2. Navigate to MCP Settings or Extensions
  3. Add a new MCP server with these details:
    • Name: chrome-devtools
    • Command: C:\\Users\\<YOUR_USER>\\AppData\\Roaming\\npm\\chrome-devtools-mcp.cmd
    • Args: ["--browser-url", "http://localhost:9222"]

Alternatively, if Cursor uses a config file similar to Codex, place the configuration in the appropriate location.

Windsurf

Windsurf configuration process:

  1. Locate the Windsurf configuration directory (typically in %APPDATA% or %USERPROFILE%)
  2. Create or edit the MCP configuration file
  3. Add the chrome-devtools-mcp server configuration similar to the Codex example
  4. Restart Windsurf

Continue.dev

For Continue.dev extension in VS Code:

  1. Open VS Code settings
  2. Find Continue configuration
  3. Add MCP server configuration in the settings JSON:
{
  "continue.mcpServers": {
    "chrome-devtools": {
      "command": "C:\\Users\\<YOUR_USER>\\AppData\\Roaming\\npm\\chrome-devtools-mcp.cmd",
      "args": ["--browser-url", "http://localhost:9222"]
    }
  }
}

Other MCP-Compatible Editors

For any editor that supports the Model Context Protocol:

  1. Locate the MCP configuration file or settings panel
  2. Add chrome-devtools-mcp as a server
  3. Provide the full path to chrome-devtools-mcp.cmd
  4. Include appropriate arguments for your use case

Running the MCP Server

Method 1: Headful Mode (Recommended)

Use this method when working with sites that have anti-bot protection:

.\scripts\Start-Chrome-Debug.ps1

This script:

  1. Terminates any existing Chrome processes
  2. Launches Chrome with a visible window
  3. Enables remote debugging on port 9222
  4. Starts the MCP server attached to that browser instance

You can manually interact with Chrome to complete CAPTCHA or Cloudflare challenges.

Method 2: Headless Mode

Use this for automated tasks on sites without bot protection:

.\scripts\Start-ChromeMCP.ps1

This script:

  1. Terminates existing Chrome processes
  2. Launches Chrome in modern headless mode
  3. Enables remote debugging
  4. Starts the MCP server in headless mode

Note: Some websites detect headless browsers and may block access.

Method 3: Manual Launch

For complete control, launch Chrome and the MCP server separately:

Step 1: Start Chrome with debugging

& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:\chrome-debug

Step 2: Start the MCP server

chrome-devtools-mcp --browser-url http://localhost:9222

Or if you want to use npx:

npx chrome-devtools-mcp --browser-url http://localhost:9222

Method 4: Let Your IDE Manage It

If you have configured the MCP server in your IDE's config file, the IDE will automatically start and manage the chrome-devtools-mcp process. You still need to ensure Chrome is running with remote debugging enabled.

Testing the Connection

Test 1: Verify Chrome Debugging Port

Open a web browser and navigate to:

http://localhost:9222/json/version

You should see JSON output like:

{
  "Browser": "Chrome/119.0.6045.199",
  "Protocol-Version": "1.3",
  "User-Agent": "Mozilla/5.0...",
  "V8-Version": "11.9.169.7",
  "WebKit-Version": "537.36"
}

If you see this, Chrome is accepting debugging connections.

Test 2: Check Open Pages

Visit:

http://localhost:9222/json

This shows all open tabs and their WebSocket debugging URLs.

Test 3: Verify MCP Server in IDE

Ask your AI assistant a simple question:

What is the status of the chrome-devtools MCP server?

Or try a browser command:

Open https://example.com and tell me what you see

Test 4: PowerShell Port Check

Verify port 9222 is listening:

netstat -ano | findstr :9222

You should see output showing port 9222 in LISTENING state.

Troubleshooting

Issue: Chrome fails to start

Symptom: Error message when running scripts, or Chrome doesn't appear

Solutions:

  1. Check if Chrome is already running:
Get-Process chrome -ErrorAction SilentlyContinue
  1. Force kill all Chrome instances:
taskkill /F /IM chrome.exe
  1. Verify Chrome installation path:
Test-Path "C:\Program Files\Google\Chrome\Application\chrome.exe"
  1. Try running Chrome manually:
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

Issue: Port 9222 already in use

Symptom: "Address already in use" error

Solutions:

  1. Find the process using port 9222:
netstat -ano | findstr :9222

Note the PID (last column).

  1. Kill that specific process:
taskkill /PID <PID> /F
  1. Or kill all Chrome processes:
taskkill /F /IM chrome.exe

Issue: MCP server won't connect

Symptom: IDE reports MCP server connection failure

Solutions:

  1. Verify chrome-devtools-mcp is installed:
chrome-devtools-mcp --version
  1. Check the path in your config file:
Get-Command chrome-devtools-mcp

This shows the actual location. Update your config.toml to match.

  1. Test manual connection:
chrome-devtools-mcp --browser-url http://localhost:9222
  1. Increase the timeout in your config file:
startup_timeout_ms = 60000

Issue: Cloudflare blocks automation

Symptom: "Checking your browser" or "Access denied" messages

Solutions:

  1. Use headful mode instead of headless:
.\scripts\Start-Chrome-Debug.ps1

  1. Manually complete the Cloudflare challenge in the visible Chrome window

  2. Do not attempt to bypass automated detection systems

  3. Some sites may simply not allow automation

Issue: Commands timeout or hang

Symptom: AI assistant doesn't respond, or reports timeouts

Solutions:

  1. Check Chrome is responsive by visiting http://localhost:9222/json

  2. Restart both Chrome and the MCP server

  3. Check Windows Firewall isn't blocking localhost connections

  4. Try a simpler test command first

Issue: Paths with spaces cause errors

Symptom: PowerShell or config parsing errors

Solutions:

  1. In PowerShell, always quote paths with spaces:
& "C:\Program Files\Google\Chrome\Application\chrome.exe"
  1. In TOML config files, use double backslashes:
command = "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"

Issue: Permission denied errors

Symptom: Access denied when creating directories or running scripts

Solutions:

  1. Run PowerShell as Administrator

  2. Check that C:\ is writable or change user-data-dir to a different location:

--user-data-dir=$env:LOCALAPPDATA\chrome-debug
  1. Adjust script execution policy if needed:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Security Considerations

Cloudflare and Anti-Bot Systems

Many websites use sophisticated bot detection:

  • Cloudflare Turnstile: Requires browser verification
  • reCAPTCHA: Needs human interaction
  • Behavioral analysis: Detects automated patterns

Best practices:

  • Always use headful mode when encountering these systems
  • Manually complete verification challenges
  • Do not attempt to bypass security measures
  • Respect robots.txt and terms of service

Ethical Automation Guidelines

Do:

  • Test your own applications
  • Automate tasks on sites where you have permission
  • Use for legitimate research and development
  • Respect rate limits and server resources

Do not:

  • Bypass security mechanisms
  • Scrape sites that prohibit automated access
  • Attempt to access unauthorized resources
  • Use for malicious purposes or terms of service violations

Network Security

Port 9222 exposure:

The Chrome debugging port (9222) should never be exposed to the internet:

  • Only bind to localhost (127.0.0.1)
  • Use Windows Firewall to block external access
  • Never use --remote-debugging-address=0.0.0.0 in production

Check firewall rules:

Get-NetFirewallRule | Where-Object {$_.DisplayName -like "*Chrome*"}

Data Privacy

When automating browser tasks:

  • Be aware of what data you are collecting
  • Don't store sensitive information in logs
  • Clear browser data periodically
  • Use isolated user-data-dir for testing

Advanced Configuration

Custom Chrome Flags

You can add additional Chrome flags to the launch scripts:

--disable-extensions
--disable-gpu
--no-sandbox
--disable-dev-shm-usage
--disable-blink-features=AutomationControlled

Edit scripts/Start-Chrome-Debug.ps1 to add flags as needed.

Multiple Browser Instances

To run multiple Chrome instances with different profiles:

# Instance 1 on port 9222
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:\chrome-debug-1

# Instance 2 on port 9223
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9223 --user-data-dir=C:\chrome-debug-2

Configure separate MCP servers for each port.

Environment Variables

Set environment variables for the MCP server:

env = { 
  SystemRoot = "C:\\Windows",
  PROGRAMFILES = "C:\\Program Files",
  CHROME_DEBUG_PORT = "9222"
}

Getting Help

If you continue to experience issues:

  1. Review this entire guide carefully
  2. Check the main README.md for updates
  3. Search existing GitHub issues
  4. Create a new issue with:
    • Your Windows version (run winver)
    • Node.js version (node --version)
    • Chrome version (chrome://version)
    • Exact error messages
    • Steps to reproduce

Additional Resources

  • chrome-devtools-mcp npm package documentation
  • Model Context Protocol specification
  • Chrome DevTools Protocol documentation
  • PowerShell scripting guides for Windows automation

Conclusion

With proper configuration, chrome-devtools-mcp provides powerful browser automation capabilities for AI coding assistants on Windows. Remember to use these tools responsibly and ethically, respecting website terms of service and security measures.