my-agent-browser

Production-ready wrapper around chrome-devtools-mcp. chrome-devtools-mcp provides the browser MCP tools, but leaves Chrome process management, multi-session sharing, and fault recovery entirely to you. This project adds the operational layer so AI agents can use the browser reliably.

中文文档

What this adds over bare chrome-devtools-mcp

Chrome Lifecycle Management

• Auto-find Chrome on your system (macOS/Linux/Windows, searches 10+ paths including Edge/Brave/Arc/Chromium)
• Lazy start — Chrome only launches on first tools/call, not at agent startup
• Multiple agent sessions share one Chrome instance via browser.lock reference counting
• Last session to exit automatically closes Chrome
• No orphans after agent crash: parent heartbeat detection + startup orphan process cleanup
• WSL / headless Linux: auto-detect and configure DISPLAY (WSLg, Wayland, X11)

Fault Recovery

• Chrome crash detection via CDP port probe — never trusts error text alone
• Confirmed crash → auto-relaunch Chrome, rewrite MCP response to tell agent to re-navigate
• MCP stale state (referencing closed tab) → restart only the MCP child process, Chrome stays
• Profile lock leftover (SingletonLock after hard kill) → auto-clean before launch

Config-driven + Anti-detection

• Headless mode, proxy, viewport size, custom launch args — all Chrome startup flags configurable
• evaluate_script stack traces are stripped of the pptr: marker and the MCP install path (which normally leaks your OS username) — measured against a site-origin trap, see anti-detection.md
• Flag recommendations backed by one-flag-at-a-time measurements rather than folklore
• Direct connection to existing Chrome (browserUrl mode, for pre-authenticated long-lived sessions)
• Opt-in background tabs via mcp.backgroundNewPages (default false), preserving explicit per-call choices

Agent Workflow Guidance (SKILL.md)

• Heavy pages: file-based snapshots to prevent DOM overflow crashes
• Error recovery: stale UIDs, timeouts, Chrome restart — correct response for each
• Multi-tab: open/extract/close pattern, UID isolation between tabs
• Scraping: URL-based pagination, lazy-load triggering, JS extraction
• Login flows: persistent profile, automated credentials, connect to existing session

Install

npx skills add briqt/my-agent-browser -g -y
npm install -g [email protected]
mkdir -p ~/.config/agent-skills/my-agent-browser
cp ~/.agents/skills/my-agent-browser/config.example.json ~/.config/agent-skills/my-agent-browser/config.json

Then register the MCP server in your agent:

Claude Code

claude mcp add browser -s user -- node ~/.agents/skills/my-agent-browser/scripts/start-mcp.js

Or add to your project’s .mcp.json:

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["~/.agents/skills/my-agent-browser/scripts/start-mcp.js"]
    }
  }
}

Codex

codex mcp add browser -- node ~/.agents/skills/my-agent-browser/scripts/start-mcp.js

Or add to ~/.codex/config.toml:

[mcp_servers.browser]
command = "node"
args = ["~/.agents/skills/my-agent-browser/scripts/start-mcp.js"]
enabled = true

Other MCP agents (Cursor, Kiro, etc.)

Add the MCP server entry per your agent’s documentation:

• Command: node
• Args: ["~/.agents/skills/my-agent-browser/scripts/start-mcp.js"]

How it works

Agent (Claude Code / Codex / Cursor / Kiro / etc.)
  ↓ MCP tool calls (native)
start-mcp.js
  ↓ reads config, manages Chrome lifecycle via browser.lock
  ↓ launches Chrome (detached) with --remote-debugging-port
  ↓ spawns chrome-devtools-mcp with --browserUrl to connect
chrome-devtools-mcp
  ↓ controls Chrome via CDP
Chrome (shared across sessions)

• Chrome runs as a detached process, shared by multiple MCP sessions
• browser.lock tracks active client count; last client to exit kills Chrome
• All browser settings live in ~/.config/agent-skills/my-agent-browser/config.json
• Restart the MCP session after config changes

Background new tabs (v1.3.0)

The MCP dependency remains chrome-devtools-mcp 1.11.0. In ~/.config/agent-skills/my-agent-browser/config.json, the default is:

{ "mcp": { "backgroundNewPages": false } }

To opt in, set:

{ "mcp": { "backgroundNewPages": true } }

Merge this field into your existing config, then restart the MCP session. mcp.backgroundNewPages is a wrapper boolean, not an upstream CLI flag; do not put it in mcp.flags. Omitted or false leaves upstream new_page behavior entirely unchanged. Only strict boolean true adds background: true when a new_page call omits background; explicit background: true or false is always respected. This works in lazy, eager and direct (browserUrl) modes, independently of stealth settings.

This is not a global focus guarantee: it does not cover Chrome’s first GUI launch, website window.open popups, or select_page { pageId, bringToFront: true }. Only bringToFront: true actively brings a selected tab to front; logical selection is not OS foreground focus. Pass pageId directly on page-scoped calls—no preceding select_page is needed. See setup and multi-tab workflow.

What the SKILL.md teaches agents

The bundled SKILL.md provides workflow guidance so agents avoid common pitfalls:

• Heavy pages — file-based snapshots to prevent DOM overflow crashes
• Scraping patterns — URL-based pagination, lazy-load triggering, JS extraction
• Multi-tab — open/extract/close pattern, UID isolation between tabs
• Error recovery — stale UIDs, timeouts, Chrome restarts
• Login flows — persistent profiles, automated credentials, existing sessions

Project structure

├── skills/my-agent-browser/
│   ├── SKILL.md                 # Agent workflow guide
│   ├── scripts/
│   │   ├── start-mcp.js        # MCP server wrapper
│   │   ├── migrate-config.js   # v1.0 → v1.1 config migration
│   │   ├── start-mcp.test.js   # Unit tests (node --test)
│   │   └── stealth-e2e.js      # End-to-end stack-trace leak check
│   ├── config.example.json      # Config template
│   ├── config.schema.json       # JSON Schema for config validation
│   └── references/
│       ├── setup.md             # Installation & configuration
│       ├── anti-detection.md    # Measured fingerprint/flag guidance
│       ├── troubleshooting.md   # Common issues & fixes
│       ├── advanced-tools.md    # Performance, Lighthouse, Console, Emulation
│       ├── network-debugging.md # Network request inspection
│       ├── scraping-patterns.md # Data extraction patterns
│       ├── multi-tab-workflow.md
│       └── javascript-execution.md
├── README.md
└── README_CN.md

Updating

npx skills update my-agent-browser -g -y
npm install -g [email protected]

Upgrading from v1.0.x, migrate your config to the v1.1 flag recommendations (dry run first, then --apply):

node ~/.claude/skills/my-agent-browser/scripts/migrate-config.js
node ~/.claude/skills/my-agent-browser/scripts/migrate-config.js --apply

It backs the file up, drops the three flags measured to hurt more than they help, and enables stack-trace hiding. Restart your agent session afterwards.

Community

Shared on LINUX DO