Chrome DevTools MCP — Windows Setup Guide

A comprehensive Windows setup guide for chrome-devtools-mcp with support for all major AI coding assistants including Codex, Cursor, Windsurf, Continue.dev, Cline, Zed, Visual Studio, GitHub Copilot, and more. This repository provides PowerShell scripts, configuration examples, and detailed troubleshooting to get Chrome browser automation working reliably on Windows 10/11.

What is chrome-devtools-mcp?

chrome-devtools-mcp is a Model Context Protocol (MCP) server that enables AI coding assistants to control Chrome browser instances. It allows your AI assistant to navigate websites, inspect DOM elements, take screenshots, interact with web pages, and analyze performance programmatically.

Works with: Codex, Cursor, Windsurf, Continue.dev, Cline, Zed Editor, Visual Studio, GitHub Copilot, JetBrains AI Assistant, and any other MCP-compatible coding assistant.

Prerequisites

Before you begin, ensure you have the following installed on your Windows system:

• Node.js (version 20.19 or higher) - Download from https://nodejs.org/
• npm (comes with Node.js)
• Google Chrome browser (latest stable version)
• Any MCP-compatible AI coding assistant (Codex, Cursor, Windsurf, VS Code with Continue/Cline, etc.)
• PowerShell 5.1 or higher (included with Windows 10/11)

Installation

Prerequisites

Before you begin, ensure you have:

• Node.js v20.19 or newer (latest maintenance LTS) - Download from https://nodejs.org/
• Google Chrome (latest stable version) - Download from https://www.google.com/chrome/
• npm (comes with Node.js)

Verify your installation:

node --version
npm --version

Recommended Method: Using npx (Official)

The official and recommended way is to use npx which requires NO global installation:

npx -y chrome-devtools-mcp@latest --help

This ensures you always use the latest version. Your IDE configuration will use:

command = "npx"
args = ["-y", "chrome-devtools-mcp@latest"]

Alternative Method: Global Installation

If you prefer a global installation (faster startup, works offline):

npm install -g chrome-devtools-mcp

Verify the installation:

chrome-devtools-mcp --version

Your IDE configuration will use:

command = "C:\\Users\\<YOUR_USER>\\AppData\\Roaming\\npm\\chrome-devtools-mcp.cmd"
args = ["--browser-url=http://localhost:9222"]

Step 2: Test Chrome Connection

Start Chrome with remote debugging enabled:

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

Important: Chrome requires a non-default user data directory when remote debugging is enabled for security reasons.

Verify Chrome is accepting connections:

Invoke-WebRequest -Uri "http://localhost:9222/json/version"

You should see a JSON response with browser version information.

Quick Start

Using the Automated Scripts

This repository includes PowerShell scripts to simplify Chrome setup:

1. Headful mode (recommended for sites with anti-bot protection):

   .\scripts\Start-Chrome-Debug.ps1

2. Headless mode (for automation without UI):

   .\scripts\Start-ChromeMCP.ps1

3. Configure your IDE automatically (supports Codex and compatible IDEs):

   .\scripts\Make-Config.ps1

Manual Configuration by IDE

For Codex IDE (Official Method)

Option 1: Using Codex CLI (Recommended)

codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

Option 2: Manual Configuration

Copy one of the example configuration files to your Codex config directory:

Copy-Item .\examples\config.headful.toml $env:USERPROFILE\.codex\config.toml

Windows 11 Specific Configuration (Official Recommendation):

On Windows 11, use the cmd wrapper and increase the startup timeout. Your .codex/config.toml should look like:

[mcp_servers.chrome-devtools]
command = "cmd"
args = [
    "/c",
    "npx",
    "-y",
    "chrome-devtools-mcp@latest",
]
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 20000

For connecting to a manually started Chrome instance, add --browser-url=http://localhost:9222 to the args.

For Cursor IDE

Quick Install:

# Use Cursor's one-click install from official repo
# Or configure manually in Settings > MCP

Copy the example configuration:

Copy-Item .\examples\config.cursor.toml $env:USERPROFILE\.cursor\config.toml

For Windsurf IDE

Copy the example configuration:

Copy-Item .\examples\config.windsurf.toml $env:USERPROFILE\.windsurf\mcp_config.toml

For VS Code Extensions (Continue.dev, Cline)

Continue.dev:

Copy-Item .\examples\config.continue.json $env:USERPROFILE\.continue\config.json

Cline:

Copy-Item .\examples\config.cline.json $env:USERPROFILE\.cline\mcp_settings.json

Or use VS Code Settings UI:

• Open Settings (Ctrl+,)
• Search for your extension's MCP settings
• Add chrome-devtools-mcp server configuration

For Zed Editor

Copy the example configuration:

Copy-Item .\examples\config.zed.json $env:APPDATA\Zed\settings.json

For Other IDEs

See the examples/ directory for additional IDE-specific configurations:

• Visual Studio
• GitHub Copilot / VS Code
• JetBrains AI Assistant & Junie
• And more...

Usage Examples

Once configured in your AI coding assistant, you can use commands like:

Example 1: Open a URL and inspect elements

Open https://example.com and tell me what the main heading says

Example 2: Count links on a page

Navigate to https://news.ycombinator.com and count how many links are on the page

Example 3: Take a screenshot

Open https://github.com and take a screenshot of the homepage

Example 4: Performance analysis

Check the performance of https://developers.chrome.com

Example 5: Inspect specific elements

Go to https://www.wikipedia.org and inspect the search input field

These examples work with any MCP-compatible AI assistant: Codex, Cursor, Windsurf, Continue.dev, Cline, and others.

Important Notes

Cloudflare and Anti-Bot Protection

Many modern websites use Cloudflare or similar anti-bot protection mechanisms. When you encounter these:

• Use headful mode (scripts/Start-Chrome-Debug.ps1) to manually complete challenges
• Do not attempt to bypass automated protection systems
• Wait for verification to complete before issuing AI commands
• Some sites may not work in headless mode due to detection mechanisms

Ethical Use

This tool is intended for:

• Testing your own web applications
• Legitimate web scraping with permission
• Automation of repetitive tasks on sites you own or have authorization to access

Do not use this tool to:

• Bypass security measures or terms of service
• Perform unauthorized data collection
• Engage in any malicious or illegal activities

Troubleshooting

Quick Checks

1. Test npx works:

   npx -y chrome-devtools-mcp@latest --help

2. Check Chrome debugging port:

   Invoke-WebRequest -Uri "http://localhost:9222/json/version"

3. Verify Node.js version (must be 20.19+):

   node --version

Common Issues

Chrome won't start on port 9222

Check if another process is using the port:

netstat -ano | findstr :9222

Kill existing Chrome processes:

taskkill /F /IM chrome.exe

MCP server fails to connect

1. Verify Chrome is running with remote debugging enabled
2. Check that http://localhost:9222/json/version returns data
3. Review the startup_timeout_ms setting in your config.toml
4. Check Windows Firewall is not blocking local connections

Error: [ERR_MODULE_NOT_FOUND]

Clear npm cache:

npm cache clean --force
Remove-Item -Recurse -Force $env:LOCALAPPDATA\npm-cache\_npx -ErrorAction SilentlyContinue

Path issues in config files

Ensure all paths use proper format:

• TOML files: Use double backslashes: C:\\Users\\...
• JSON files: Use double backslashes: C:\\Users\\...

For complete troubleshooting, see docs/TROUBLESHOOTING.md

Compatible IDEs and Coding Assistants

This setup works with any MCP-compatible AI coding assistant on Windows:

• Codex IDE - Full MCP support with config.toml

  • Install via CLI: codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
  • Official MCP Guide
  • Windows 11: Use cmd wrapper with 20 second timeout (see config examples)

• Cursor - Configure via MCP settings

  • One-click install available from official repository
  • Manual configuration in Settings > MCP

• Windsurf - Supports MCP servers

  • Official MCP Guide

• Continue.dev - MCP integration for VS Code

  • Install MCP servers via extension settings

• Cline - VS Code extension (formerly Claude Dev)

  • Official MCP Guide

• Zed Editor - Native MCP protocol support

  • Uses "context_servers" configuration

• Visual Studio - Built-in MCP support

  • One-click install available

• Copilot / VS Code - GitHub Copilot with MCP

  • Install via VS Code CLI: code --add-mcp '{"name":"chrome-devtools","command":"npx","args":["chrome-devtools-mcp@latest"]}'

• JetBrains AI Assistant & Junie - MCP support in IntelliJ IDEA and other JetBrains IDEs

• Other editors with MCP client implementations

All configurations use the official recommended method:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Configuration may vary slightly by editor. Refer to docs/USAGE.md and examples/ for detailed setup instructions for each platform.

Documentation

• Detailed Usage Guide - Complete setup and configuration
• Troubleshooting Guide - Solutions to common problems
• Example Configurations - Ready-to-use config files for all IDEs
• PowerShell Scripts - Automation helpers
• Test Prompts - Sample commands to verify setup

Official chrome-devtools-mcp Resources

• Official GitHub Repository
• npm Package
• Tool Reference
• Official Troubleshooting
• Contributing Guide

Contributing

Contributions are welcome! If you encounter issues or have improvements:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request with a clear description of changes

Please ensure all scripts and configurations are tested on Windows 10/11 with multiple IDEs before submitting.

Areas for Contribution:

• Additional IDE configurations
• Improved PowerShell scripts
• Better troubleshooting documentation
• Translation to other languages
• Bug fixes and performance improvements

Issues

If you encounter problems:

1. Check the troubleshooting section in docs/TROUBLESHOOTING.md
2. Search existing issues on GitHub
3. Create a new issue with detailed information:
   • Windows version
   • Node.js version
   • Chrome version
   • IDE/coding assistant name and version
   • Error messages or logs

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

Built for the chrome-devtools-mcp package by the MCP community. Special thanks to:

• The Chrome DevTools team at Google
• All contributors working to make browser automation accessible on Windows
• The MCP community for supporting multiple AI coding assistants
• Contributors to Codex, Cursor, Windsurf, Continue.dev, Cline, and other AI coding tools