How to Connect Your AI Agent to Your Real Chrome Browser

By default, every AI agent that tries to interact with a website opens a fresh, isolated browser window. No logins. No context. No access to the tabs you actually have open.

This is why agents fail at tasks like navigating tools you're already authenticated into, or running performance audits on your live staging environment. The agent and your browser simply aren't talking to each other.

Chrome DevTools MCP solves this. It's an official MCP server built by Google's Chrome DevTools team that connects your AI agent directly to a live Chrome instance — giving it the ability to automate, inspect, debug, and analyze whatever is on screen.

This tutorial covers both setups: a quick-start path using --autoConnect for general use, and the persistent authenticated profile approach for workflows that require real logins.

What You Need Before You Start

• Node.js v22 or newer. The MCP server won't run on older versions. Check with node --version.
• Chrome stable channel — any recent version works for the --autoConnect approach. If you need authenticated sessions, the setup below handles that separately.
• An MCP-compatible agent. Claude Code, Cursor, Gemini CLI, Cline, VS Code Copilot, and Windsurf all work. The config structure is nearly identical across all of them.

Path 1: Quick Start with --autoConnect

This is the fastest path. Your agent connects to a Chrome instance that's already running, Chrome asks for your permission, and you're in.

Step 1: Add Chrome DevTools MCP to your agent config

For most JSON-based MCP configs (Cursor, Gemini CLI, Cline, Windsurf), add this block under mcpServers:

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

For Claude Code, the canonical method is the CLI command — no JSON editing needed:

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

For Windows users, use this config block instead:

{
  "mcpServers": {
    "chrome-devtools": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "chrome-devtools-mcp@latest", "--autoConnect"],
      "env": {}
    }
  }
}

Where the config file lives:

Agent	Location
Cursor	Settings → MCP → New MCP Server
Gemini CLI	~/.gemini/settings.json
Cline	MCP configuration UI in settings
VS Code Copilot	Settings → MCP → Add MCP Server
Claude Code	Use the CLI command above

Step 2: Make sure Chrome is running

--autoConnect requires Chrome to already be open. If you have multiple active profiles, the MCP server will connect to the default profile as determined by Chrome. The agent will have access to all open windows within that profile.

Step 3: Allow the permission dialog

When the Chrome DevTools MCP server attempts to connect to your running Chrome instance, it shows a dialog asking for user permission. Clicking Allow grants the session. A banner will appear at the top of Chrome reading "Chrome is being controlled by automated test software." This is expected — it's Chrome confirming the active connection.

This prompt appears every session, by design.

Step 4: Test the connection

Ask your agent:

"Navigate to https://example.com and take a screenshot."

If it returns a screenshot of the page in your running Chrome window, everything is working.

Path 2: Persistent Authenticated Profile (For Sites Requiring Login)

The --autoConnect approach works for general use, but it won't let you reliably automate sites where you need to be logged in. There's a harder limitation here worth knowing: starting with Chrome 136, remote debugging is blocked on your default profile for security reasons. If you try to start your main Chrome instance with --remote-debugging-port, it will fail.

The solution is --user-data-dir. This flag tells Chrome to create and use a separate profile directory. Chrome automatically creates this directory if it doesn't exist. Everything you do in that browser window — logins, cookies, extensions, browsing history — gets saved to that directory. Close Chrome and reopen it with the same --user-data-dir, and all your sessions are still there.

Step 1: Launch Chrome with remote debugging enabled

Close any existing Chrome windows first. Then launch Chrome with both flags:

Mac:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.chrome-debug-profile"

Windows (Command Prompt):

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

Chrome will open a new window using your separate debug profile. Verify it's working by opening http://127.0.0.1:9222 in a different browser — you should see a JSON response listing Chrome's debugging endpoints.

Step 2: Log into your accounts

In this debug Chrome window, sign into every site you want the agent to access. GitHub, your CMS, any internal tools. These sessions are saved to your --user-data-dir profile and will persist between restarts.

Step 3: Configure your agent to connect via --browserUrl

For Claude Code:

claude mcp add --transport stdio chrome-devtools -- npx -y chrome-devtools-mcp@latest --browserUrl=http://127.0.0.1:9222

For JSON-based configs:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--browserUrl=http://127.0.0.1:9222"]
    }
  }
}

The --browserUrl flag tells the MCP server to connect to the Chrome instance already running on port 9222, rather than launching a new one.

Step 4: Make it convenient — create a launch alias

Typing the full Chrome launch command every time is tedious. Add this alias to your ~/.zshrc or ~/.bashrc:

alias chrome-debug="/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=\"$HOME/.chrome-debug-profile\" > /dev/null 2>&1 &"

Reload with source ~/.zshrc, then just type chrome-debug to launch your authenticated session.

What the Agent Can Actually Do

Chrome DevTools MCP exposes 26 tools organised across 6 categories: input automation (click, drag, fill, fill_form, hover, handle_dialog, upload_file), navigation (navigate_page, new_page, list_pages, select_page, close_page, navigate_page_history, wait_for), and additional categories for inspection, debugging, network analysis, and performance.

In practice, this breaks down into four useful areas:

Automation — navigate, click, fill forms, handle dialogs, upload files. Puppeteer handles the underlying timing, so the agent waits for page state before acting rather than firing into a loading screen.

Inspection — read the live DOM, check CSS, take screenshots, pull console errors with source-mapped stack traces. The agent sees exactly what you'd open DevTools to inspect manually.

Network analysis — inspect request/response headers, identify CORS failures, read API payloads. Useful for diagnosing broken features, not just writing code.

Performance — record traces, extract Core Web Vitals, run Lighthouse-style audits. The agent can audit a page, identify the issue, fix the code, and re-audit — all in one loop.

AI researcher Delip Rao demonstrated an early example: using Gemini CLI as the client, he had the agent open Google Scholar, search for a term, and download the top 5 PDF results — all through automated browser actions. Any task you could previously script with a browser, you can now just describe in natural language.

The Security Risks — Read This Part

Chrome DevTools MCP exposes the content of the browser instance to MCP clients, allowing them to inspect, debug, and modify any data in the browser or DevTools. Avoid sharing sensitive or personal information that you don't want to share with MCP clients.

Two specific risks worth understanding:

Prompt injection. A malicious website can embed hidden instructions in its page content designed to redirect what your agent does next. If the agent is browsing while connected to an authenticated session, a compromised page could attempt to use your live sessions as an attack surface. This is a known vector — not theoretical.

Exposed debugging port. Port 9222 is local-only by default. If you're on a shared network or have port-forwarding rules in place, verify this port isn't reachable externally.

Rules to follow:

• Only run the authenticated session setup for development and task-specific work — not general browsing
• Don't use the debug profile for banking, email, or other sensitive personal accounts
• Close Chrome when you're done; the debugging port closes with it
• Google collects usage telemetry (tool invocation rates, latency, environment info) by default — add --no-usage-statistics to your config args to opt out

Quick Reference

Goal	Flag to use
Connect to your running Chrome	--autoConnect
Connect to authenticated session	--browserUrl=http://127.0.0.1:9222
Use a separate persistent profile	--user-data-dir="/path/to/profile"
Clean isolated session	--isolated=true
Headless, no visible window	--headless=true
Opt out of usage telemetry	--no-usage-statistics

Full documentation and client-specific setup instructions are in the Chrome DevTools MCP GitHub repository.

Where to Start

If you just want to test it: use the --autoConnect path, ask the agent to screenshot your current tab, and verify it connects to your real Chrome window rather than a new one.

If you need authenticated workflows: set up the persistent debug profile once, log into your accounts, and use --browserUrl. Every subsequent session, just run chrome-debug and you're ready.

The main thing to internalise: this is powerful precisely because it has no guardrails at the session level. Treat it accordingly.