Chrome for Agents

Use your real, already-open Chrome browser with agentic CLI tools like Codex, Claude Code, Gemini CLI, and other MCP-compatible clients.

Instead of launching a fresh browser, this setup lets your agent connect to your current Chrome session so it can work with the tabs, logins, cookies, and page state you already have open.

What is this?

This repo is a simple starter kit for connecting AI agents to a live Chrome session using the official Chrome DevTools MCP server.

In plain English:

• you open Chrome yourself
• you keep using your normal profile
• your coding agent connects to that same browser
• the agent can inspect and interact with pages you already have open

What exactly does it do?

Once connected, an agent can do things like:

• read the current page structure
• inspect console errors
• inspect network requests
• take screenshots
• click buttons and links
• type into inputs
• navigate pages
• use the state of the tab you are already logged into

That means it is useful for tasks like:

• reviewing LinkedIn invites in the tab you already opened
• debugging a site that only breaks when you are logged in
• filling in a form that is hard to automate from a fresh browser
• reproducing bugs using your real account state

What this is not

This is not a new browser automation framework.

It is a thin, practical setup around the official chrome-devtools-mcp server so your agent tools can use live Chrome through MCP.

Why this is useful

Most agent tools are great at coding, but browser tasks are awkward when they start in a clean browser with no session.

This approach solves that by letting the agent work in the browser you are already using.

Benefits:

• keeps your real login/session state
• avoids redoing auth flows
• works better for real-world debugging
• works across multiple agent tools
• uses the official Chrome MCP server instead of a custom CDP script

How it works

1. Chrome exposes your current browser session for debugging.
2. chrome-devtools-mcp connects to that running Chrome instance.
3. Your agent client talks to the MCP server.
4. The agent can now inspect and interact with your live Chrome tabs.

Requirements

• Chrome 144+
• Node.js 20.19+
• an MCP-capable client such as Codex, Claude Code, Gemini CLI, Cursor, etc.

Quick start

1. Enable remote debugging in Chrome

Open this page in Chrome:

chrome://inspect/#remote-debugging

Turn on remote debugging for your current Chrome session.

If Chrome asks whether to allow the debugging connection, approve it.

2. Add the MCP server to your agent tool

Use the official server:

npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics

--autoConnect tells the MCP server to attach to your already-running Chrome session.

3. Restart your client and use it

Example prompts:

• Check my currently open LinkedIn invitations tab and group obvious sales pitches separately.
• Inspect the current tab for console errors and failed network requests.
• Use my already open logged-in dashboard tab and explain why this page is broken.
• Open the existing Chrome tab for this app and click through the signup flow.

Client setup

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.chrome-devtools]
command = 'npx'
args = ["-y", "chrome-devtools-mcp@latest", "--autoConnect", "--no-usage-statistics"]
startup_timeout_sec = 45.0

Claude Code

CLI install:

claude mcp add -s user chrome-devtools -- npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics

Or use the JSON shape in examples/claude-mcp.json.

Gemini CLI

CLI install:

gemini mcp add -s user chrome-devtools npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics

Or use the JSON shape in examples/gemini-settings.json.

Generic MCP config

For clients that accept MCP JSON config, use:

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

Safety and privacy

This setup gives the MCP client access to the Chrome profile it connects to.

That means the agent may be able to see:

• open tabs
• page contents
• logged-in sessions
• browser-visible personal data

Use it intentionally.

Good practice:

• close tabs you do not want the agent to touch
• avoid using sensitive accounts while debugging is enabled
• only grant access when you actually want browser help
• prefer a separate profile if you need stronger isolation

Best use cases

Use this when the page already depends on:

• being logged in
• existing cookies/session state
• a specific open tab
• manual setup already done by you

When a separate browser is better

Use a clean browser or Playwright/Puppeteer flow when you need:

• isolated tests
• CI automation
• reproducible end-to-end test runs
• zero access to your personal browsing session

Fallback mode

If --autoConnect is unavailable or unreliable on your machine, use a dedicated Chrome instance with a debugging port.

Start Chrome like this on Windows:

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:TEMP\chrome-profile-mcp"

Then configure your MCP client to use:

npx -y chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:9222 --no-usage-statistics

This is safer because it uses a separate Chrome profile.

Included in this repo

• examples/codex-config.toml - Codex config snippet
• examples/claude-mcp.json - Claude-compatible MCP JSON shape
• examples/gemini-settings.json - Gemini settings example
• examples/generic-mcp.json - generic MCP config
• skills/chrome-live-session/SKILL.md - reusable skill guidance for agent workflows

Troubleshooting

The agent cannot see my current tabs

• make sure Chrome is already open
• make sure remote debugging is enabled in chrome://inspect/#remote-debugging
• restart the MCP client after changing config
• check that your client really loaded the chrome-devtools MCP server

The agent opens a fresh browser instead of my live one

• verify you used --autoConnect
• make sure your Chrome version is new enough
• if needed, use the fallback --browserUrl approach

The client says the MCP server failed to start

Check these first:

• node -v
• npx -y chrome-devtools-mcp@latest --help

Credit

This repo packages a practical pattern around the official Chrome DevTools MCP server so agentic CLI users can work with live Chrome more easily.

Official project:

• Chrome DevTools MCP: https://github.com/ChromeDevTools/chrome-devtools-mcp