Content
<p align="center">
<img src="assets/hero.svg" alt="Claude Chrome Automation for Windows" width="100%" />
</p>
<h1 align="center">Claude Chrome Automation for Windows</h1>
<p align="center">One-click browser automation for Claude Code on Windows.</p>
<p align="center">
<a href="https://github.com/davidchen99/claude-chrome-automation-windows/blob/main/README.zh-CN.md">中文说明</a>
·
<code>limited</code> mode
·
<code>full-auto</code> mode
</p>
<p align="center">
<img src="https://img.shields.io/badge/platform-Windows-2563EB?style=flat-square" alt="Windows" />
<img src="https://img.shields.io/badge/Claude%20Code-MCP%20Launcher-0F172A?style=flat-square" alt="Claude Code MCP Launcher" />
<img src="https://img.shields.io/badge/modes-limited%20%7C%20full--auto-1D4ED8?style=flat-square" alt="Modes" />
<img src="https://img.shields.io/badge/license-MIT-16A34A?style=flat-square" alt="MIT License" />
</p>
This project packages a Windows-native workflow for people who want Claude to control Chrome without manually wiring MCP every time.
It gives you:
- a dedicated Chrome instance on `127.0.0.1:9222`
- a reusable login-preserving browser profile
- a `limited` launcher for safer browser-first automation
- a `full-auto` launcher for maximum autonomy
- project-local MCP config instead of fragile per-user setup
## At a glance
- Double-click launchers for native Windows usage
- Dedicated Chrome debug browser on `127.0.0.1:9222`
- Persistent login session through a separate browser profile
- Safer `limited` mode for browser-first tasks
- Aggressive `full-auto` mode for high-trust automation
- Project-local MCP config instead of global Claude edits
## Visual flow
<p align="center">
<img src="assets/flow.svg" alt="Workflow diagram" width="100%" />
</p>
## Contents
- [Why this exists](#why-this-exists)
- [Modes](#modes)
- [Who this is for](#who-this-is-for)
- [Quick start](#quick-start)
- [How it works](#how-it-works)
- [Security notes](#security-notes)
- [Troubleshooting](#troubleshooting)
## Why this exists
Most browser automation examples for Claude stop at "install chrome-devtools-mcp and make it connect once."
That is not enough for normal Windows users.
The real gap is productization:
- Windows users want double-click launchers
- they want Chrome to reopen in the right debugging mode
- they want login state to persist
- they want a safer everyday mode and a more aggressive mode
- they do not want to hand-edit Claude config files just to try browser automation
This repo packages that missing layer into a reusable template.
## Core idea
The workflow is simple:
1. Launch a dedicated Chrome debug session
2. Connect Claude Code to it through a local MCP config
3. Choose the right autonomy level for the task
That sounds small, but in practice it removes most of the friction people hit on Windows.
## Modes
| Mode | Best for | Permission style |
| --- | --- | --- |
| `limited` | everyday browsing, clicking, scraping, screenshots | browser-first, safer |
| `full-auto` | high-trust tasks with minimal interruption | `--dangerously-skip-permissions` |
## Why it is different
### 1. Native Windows first
This is designed specifically for Windows, not adapted from a Unix-first setup.
- Uses `cmd /c npx ...` for MCP startup
- Uses `.bat` launchers for double-click usage
- Works with Windows paths and profile handling
### 2. Two-mode automation
Most examples stop at "make Claude control Chrome".
This project adds a useful operating model:
- `limited` mode
- allows browser automation
- blocks general `Bash`
- blocks `WebFetch`
- keeps Claude focused on browser work
- `full-auto` mode
- launches Claude Code with `--dangerously-skip-permissions`
- best for advanced users who want less interruption
### 3. Dedicated browser profile
The launcher uses a dedicated Chrome profile directory:
- login state is preserved
- cookies are preserved
- browser automation is isolated from the user's normal browser
### 4. Plug-and-play packaging
Users can download the folder and launch it directly after they have:
- Claude Code installed
- Node.js installed
- Google Chrome installed
No manual MCP editing is required because the launcher passes a local MCP config at runtime.
## Who this is for
- Windows users who want Claude to browse, click, read, and extract page content
- people who need persistent login sessions in a dedicated automation browser
- users who want a practical launcher instead of a configuration tutorial
- advanced users who want a full-auto mode for high-trust tasks
## Folder structure
```text
claude-chrome-automation-windows/
README.md
README.zh-CN.md
launch-limited.bat
launch-full-auto.bat
config/
chrome-devtools.mcp.json
limited-settings.json
scripts/
start-chrome-debug-9222.bat
```
## Requirements
- Windows
- Claude Code installed and available as `claude`
- Node.js and `npx`
- Google Chrome
## Install
1. Clone or download this repository.
2. Make sure `claude`, `node`, `npx`, and Chrome are available on your Windows machine.
3. Double-click `launch-limited.bat` or `launch-full-auto.bat`.
## Quick start
### Limited mode
Double-click:
- `launch-limited.bat`
This mode is recommended for most users.
### Full-auto mode
Double-click:
- `launch-full-auto.bat`
This mode is more aggressive and less safe.
## First login
The first time you launch the dedicated Chrome window, log into the sites you need inside that window.
That login state is usually preserved for future launches.
## How it works
### Dedicated Chrome instance
The script starts Chrome with:
- remote debugging enabled on `127.0.0.1:9222`
- a dedicated user-data directory under the current Windows user profile
### Claude + project-local MCP
Instead of relying on global Claude MCP configuration, this project passes:
- `--mcp-config config\\chrome-devtools.mcp.json`
This makes the package easier to share.
### Limited mode permissions
`limited` mode passes:
- `--settings config\\limited-settings.json`
That config:
- allows all tools from the local `chrome_devtools` MCP server
- denies `Bash`
- denies `WebFetch`
- uses `acceptEdits`
## Security notes
### Limited mode
Lower risk than full-auto, but not risk-free.
Claude can still:
- browse pages
- click buttons
- read visible page content
- interact with logged-in sites inside the dedicated browser
### Full-auto mode
This mode is intentionally high-trust.
Claude Code is launched with:
- `--dangerously-skip-permissions`
Use it only when you understand the implications.
## Common use cases
- open a page and summarize its contents
- log into a web tool once, then reuse that session
- click through repetitive browser tasks
- capture screenshots
- pull structured data from browser-visible pages
## Troubleshooting
### Chrome opens but Claude cannot browse
Check:
- Chrome is running
- port `9222` is available
- Claude Code is installed
- `npx` is available
### Claude asks to log in repeatedly
Make sure you logged into the dedicated Chrome window, not your normal Chrome window.
## Notes for publishing
If you want to distribute this as a repo:
- keep the launcher filenames stable
- avoid user-specific absolute paths
- do not commit personal Chrome profile data
