MCP 服务器

Chrome MCP Bridge

AI-driven browser automation for real Chrome with cookies, login sessions, and extensions intact, enabling Claude Code to control a visible Chrome browser via the Chrome DevTools Protocol.

README

Chrome MCP Bridge

Part of a 24/7 fully-automated unmanned software development system. This is a standalone component; the core system is proprietary.

AI-driven browser automation for real Chrome — with cookies, login sessions, and extensions intact.

This stdio MCP server lets Claude Code (claude --print) control a visible Chrome browser through the Chrome DevTools Protocol. Unlike headless automation, everything happens in a real browser window — government reviewers can watch every action live.

What It Does

An AI agent can:

Navigate to any URL (government portals, internal systems)
Read page content and accessibility trees
Fill forms automatically (text fields, dropdowns, radio buttons)
Click buttons and submit forms
Take screenshots at every step for audit trails
Execute JavaScript for advanced interactions

All operations use the user's real Chrome profile — existing logins, cookies, and sessions are preserved.

Requirements

Requirement	Version
Python	3.10+
Google Chrome	macOS
pip packages	`mcp`, `websockets` (installed by setup)

Quick Start (Clean Machine)

# 1. Clone and install
cd chrome-mcp-bridge
bash setup.sh

# 2. Launch Chrome with debugging
./launch_chrome.sh

# 3. Run the demo
python3 scripts/demo.py

Screenshots are saved to demo_output/.

Usage with Claude Code

Option A: One-shot command

claude --print --mcp-config mcp-config.json \
  "Navigate to google.com and take a screenshot"

Option B: Add to any project

Copy the generated mcp-config.json into your project as .mcp.json, or add the server block manually:

{
  "mcpServers": {
    "chrome": {
      "command": "python3",
      "args": ["/absolute/path/to/src/chrome_mcp_server.py"],
      "env": { "CHROME_CDP_PORT": "9222" }
    }
  }
}

setup.sh generates mcp-config.json with the correct absolute path automatically.

Available Tools

Tool	Description
`navigate(url)`	Navigate to a URL
`screenshot()`	Capture JPEG screenshot
`click(coordinate)`	Click at `[x, y]`
`type_text(text)`	Type keyboard text
`key(keys)`	Press key combo (e.g. `cmd+a`, `Enter`)
`scroll(coordinate, direction, amount)`	Scroll at position
`hover(coordinate)`	Hover mouse
`drag(start, end)`	Drag from `[x1,y1]` to `[x2,y2]`
`find(query)`	Find elements by natural language description
`form_input(ref, value)`	Fill form field (CSS selector or `x,y`)
`read_page(filter)`	Read accessibility tree (`all` / `interactive`)
`get_page_text()`	Extract visible page text
`javascript(code)`	Execute JS in active tab
`read_console()`	Read browser console logs
`tabs_context()`	List open tabs
`tabs_create(url)`	Open new tab
`tabs_close(tab_id)`	Close tab
`tabs_switch(tab_id)`	Switch to tab
`file_upload(paths)`	Upload files to file input
`wait(duration)`	Wait N seconds

Architecture

claude --print / Claude Code
        | stdio (MCP JSON-RPC)
        v
  chrome_mcp_server.py
        |
        +-- Primary: chrome-native-host socket (Claude extension)
        +-- Fallback: Chrome DevTools Protocol (CDP) via websocket
                |
                v
          Google Chrome (--remote-debugging-port=9222)

The server auto-detects which backend is available. CDP mode works without the Claude extension.

Demo Script

scripts/demo.py runs an end-to-end demonstration:

Navigates to a form page (httpbin.org)
Screenshots the empty form
Finds and fills all form fields automatically
Screenshots the filled form
Submits the form
Screenshots and reads the result

# Chrome must be running with debugging first
./launch_chrome.sh
python3 scripts/demo.py

Output screenshots are saved to demo_output/ for review.

Troubleshooting

"Could not connect to Chrome"

Ensure Chrome is running with --remote-debugging-port=9222
Verify: curl http://localhost:9222/json/version

Chrome won't start (port in use)

Another Chrome instance may hold the port. Close it or use a different port:
```
./launch_chrome.sh 9333
```

Profile/cookies not loading

If Chrome is already running normally, it locks the profile. Close Chrome first, then launch via the script.

setup.sh fails on pip install

Ensure pip3 is available: python3 -m ensurepip --upgrade
Or use a virtual environment: python3 -m venv .venv && source .venv/bin/activate && bash setup.sh