# Codex Chrome MCP Proxy v3

> Sanitized public Chrome MCP bundle for Codex: persistent CDP proxy, real Chrome login-state control, background tabs, focus protection, multi-agent isolation, and cached chrome-devtools-mcp startup fallback.

## Install

Save as a script file and run:

---
name: codex-chrome-mcp-proxy-v3
description: Codex-ready Chrome MCP proxy bundle for controlling the user's real Chrome through a persistent CDP proxy with focus protection and multi-agent isolation.
---

# Codex Chrome MCP Proxy v3

Use this asset when Codex browser work must go through the user's real Google Chrome instead of Codex Browser, a temporary Playwright profile, or a browser extension bridge.

This bundle packages a public, sanitized version of the Chrome MCP setup:

- `scripts/cdp-proxy.mjs` - persistent CDP proxy with request-id remapping, session routing, background tabs, timeout cleanup, and reconnect handling.
- `scripts/chrome-mcp-proxy.sh` - MCP stdio entrypoint that starts/reuses the persistent proxy and launches `chrome-devtools-mcp`, preferring an explicit or cached binary before falling back to `npx -y`.
- `scripts/kill-old-chrome-mcp.sh` - conservative cleanup helper for stale `chrome-devtools-mcp` processes.
- `templates/codex-config.toml` - Codex MCP server config snippet.
- `templates/mcp.json` - generic MCP config snippet.
- `AGENTS.md` - agent rule that forces browser operations through Chrome MCP.

## Current Codex Delta

This version reflects the May 26, 2026 Codex setup:

- the `chrome` MCP server uses `scripts/chrome-mcp-proxy.sh` on proxy port `9401` and Chrome DevTools port `9222`;
- bundled Codex browser, bundled Chrome, and computer-use plugins should stay disabled for strict real-Chrome routing;
- the wrapper checks `CHROME_DEVTOOLS_MCP_BIN` and existing npm cache binaries first, because `npx -y chrome-devtools-mcp@0.19.0` can hang during MCP stdio startup on some hosts;
- if a Codex `notify` hook launches a computer-use app, comment it out before relying on Chrome MCP as the sole browser path.

## What It Solves

Codex's built-in browser tools are useful for ordinary page testing, but they are not enough when a task requires:

- the user's real Chrome login state, cookies, extensions, bookmarks, and existing tabs;
- CDP-level network, console, runtime, performance, and target control;
- background tabs that do not steal focus from the user;
- multiple agents sharing one Chrome without request or event collisions;
- a persistent connection that avoids repeated Chrome remote-debugging prompts.

The required path is:

```text
Codex MCP client
  -> scripts/chrome-mcp-proxy.sh
  -> chrome-devtools-mcp
  -> scripts/cdp-proxy.mjs on 127.0.0.1:9401
  -> real Google Chrome DevTools endpoint
```

## Install

1. Copy the scripts to a stable local directory, for example:

```bash
mkdir -p "$HOME/scripts"
cp scripts/cdp-proxy.mjs scripts/chrome-mcp-proxy.sh scripts/kill-old-chrome-mcp.sh "$HOME/scripts/"
chmod +x "$HOME/scripts/chrome-mcp-proxy.sh" "$HOME/scripts/kill-old-chrome-mcp.sh"
```

2. Install Node dependencies next to `cdp-proxy.mjs`:

```bash
cd "$HOME/scripts"
npm install ws
```

If `npx -y chrome-devtools-mcp@0.19.0` hangs during MCP startup, either run it once in an interactive shell so npm creates a cache binary, or set `CHROME_DEVTOOLS_MCP_BIN` to a known executable:

```bash
export CHROME_DEVTOOLS_MCP_BIN="$HOME/.npm/_npx/<cache-id>/node_modules/.bin/chrome-devtools-mcp"
```

3. Enable remote debugging for the current Chrome profile:

```text
Open chrome://inspect/#remote-debugging
Enable "Allow remote debugging for this browser instance"
```

4. Add the Codex MCP server config from `templates/codex-config.toml` to `~/.codex/config.toml`.

5. Restart Codex so the new MCP server is loaded.

## Codex Routing Rule

For browser-related tasks, route through Chrome MCP only:

- page open/navigation/click/type;
- screenshots and visual verification;
- DOM/page inspection;
- authenticated pages and existing tabs;
- network, console, runtime, performance, memory checks;
- file upload flows.

Do not fall back to Codex Browser, a temporary browser profile, AppleScript, shell UI automation, or a direct `chrome-devtools-mcp` connection.

Non-browser work such as code edits, tests, CLI commands, and API calls can still use the normal local tools.

## Health Check

```bash
curl -s --noproxy '*' http://127.0.0.1:9401/proxy/status
```

Expected:

```json
{
  "chromeConnected": true,
  "pendingRequests": 0
}
```

If Chrome restarted, the proxy should reconnect. Chrome may ask for remote-debugging permission once after a restart.

## Safety Rules

- Always go through `cdp-proxy.mjs`; never connect `chrome-devtools-mcp` directly to Chrome.
- Do not launch a throwaway Chrome profile for authenticated work.
- Do not include proxy environment variables in the MCP server config.
- Keep Codex browser/computer-use backends disabled when this asset is the required browser-control path.
- Do not kill the active MCP process from the current session.
- Use `scripts/kill-old-chrome-mcp.sh` only for stale process cleanup.
- Treat cookies, local storage, passwords, tokens, and private page data as sensitive.
- Prefer background tabs unless the user explicitly wants a visible page.

## Why `stage_only`

This asset can modify a user's browser session, inspect authenticated pages, and run JavaScript in pages. It should be installed as a staged bundle and reviewed before activation.


---
Source: https://tokrepo.com/en/workflows/codex-chrome-mcp-proxy-v3-5846fbcf
Author: henuwangkai