Codex Chrome MCP

English | 中文

Exposes Codex's Chrome ("Control Chrome with Codex") plugin as an MCP server, so any MCP client (Cursor, Claude Code, etc.) can drive your real, logged-in Chrome — navigate, snapshot the DOM, click, type, screenshot, run Playwright, and more.

How it works

Unlike Computer Use (a self-contained .exe), the Chrome plugin is a Node bundle (browser-client.mjs) that talks to Chrome through a Codex-owned native pipe and the Codex Chrome extension:

MCP client (Cursor, ...)
  ↓ MCP (stdio)
codex-chrome-mcp  ──imports──▶ <Codex plugin cache>/chrome/<ver>/scripts/browser-client.mjs
  ↓ named pipe  \\.\pipe\codex-browser-use\<uuid>
extension-host.exe  ↔  Codex Chrome extension (hehggadaopoacecdllhhajmbjkdcmajg)
  ↓
your Chrome tabs

This server provides the host-environment shims that the Codex node_repl normally supplies (privileged pipe bridge, per-turn metadata, security mode, approval callback, fetch) and then reuses the official browser-client, so the API always matches your installed plugin.

Related MCP server: Codex Control Chrome MCP

Requirements

• Windows 10/11

• Node.js 18+

• ChatGPT desktop (formerly Codex Desktop) with the "Chrome" plugin installed ("Control Chrome with ChatGPT"; compatibility identifiers keep the Codex-era names — ~/.codex, codex-browser-use, …). The plugin's browser-client.mjs must exist under ~/.codex/plugins/cache/openai-bundled/chrome/…, or use the vendored client under vendor/ (required for raw CDP, see below).

• A live codex-browser-use pipe — created by the extension/host. In practice, keep the ChatGPT desktop app running and Chrome open with its extension enabled.

Install

See INSTALL.md. In short: npm install && npm run build, then register node <repo>/bin/codex-chrome-mcp.js as a stdio MCP server.

Tools

Raw CDP (developer mode)

cdp_send / cdp_events expose the tab's cdp capability — raw Chrome DevTools Protocol for developer/debugging work (network interception, emulation, profiling, breakpoints). Upstream's own guidance applies: prefer the higher-level tools for ordinary automation.

Requirements — all three must hold, otherwise the tools fail with Capability is not available: cdp:

1. A 26.727+ browser-client: only 26.727+ injects the cdp tab capability (the plugin cache currently ships 26.715.31925, which lacks it). This repo vendors a working client at vendor/chrome-26.727.51351/; point CODEX_CHROME_CLIENT at its scripts/browser-client.mjs and keep the scripts/ and docs/ siblings together (else browser_documentation breaks).

2. full_cdp_access_enabled = true in ~/.codex/browser/config.toml — the client's full-CDP gate reads it through the shim's nodeRepl.config surface (src/runtime.ts).

3. The tab is on an http(s) origin: navigate first; raw CDP is scoped to the tab's current web origin.

Behavior:

• The first cdp_send auto-attaches the debugger extension-side; Chrome shows its "started debugging" bar. Event domains (Page, Network, …) emit nothing until their .enable command is sent.

• To observe events for an action: take a cursor with cdp_events, perform the action, then read from that cursor with after_sequence; page while hasMore is true (truncated means older events were evicted; reuse the same filters while paging).

• Child targets (iframes, workers): discover selectors from Target.attachedToTarget events, then pass session_id or target_id.

Guardrails enforced upstream (some commands are refused with guidance):

• No top-level Document interception — intercept sub-resources or page-initiated requests instead.

• Fetch.enable patterns must name an explicit non-Document resourceType (XHR, Fetch, Script, …); an unscoped pattern implicitly includes Document and is rejected.

• No Fetch.disable — clear interception with Fetch.enable({ patterns: [] }).

• Breakpoints: a pause blocks the Runtime.evaluate that triggered it. Trigger fire-and-forget (awaitPromise: false, or wrap in setTimeout(fn, 0)), then poll Debugger.paused, inspect with Debugger.evaluateOnCallFrame, and Debugger.resume.

Verification harnesses (repo root): node verify-cdp.mjs runs the built modules end to end (capability injection, auto-attach, Runtime.evaluate, event paging); node verify-stdio.mjs spawns bin/codex-chrome-mcp.js over stdio exactly as an MCP client does. Verified end to end 2026-08-04 against the vendored 26.727 client.

Configuration (env)

Caveats

• Not self-contained/redistributable: it reuses the proprietary plugin from your machine and is tied to the installed plugin version.

• Requires a live codex-browser-use pipe (generally the ChatGPT desktop app + the Chrome extension active).

• May share/contend with the app's own browser session; behavior can change across app/plugin updates.

• Raw CDP attaches Chrome's debugger to the tab (visible "started debugging" bar), is scoped to the tab's current web origin, and upstream refuses some commands (see Raw CDP). If CDP changes page/browser state beyond ordinary navigation and the change is left in place, upstream guidance is to tell the user what changed.

Disclaimer

Uses OpenAI's proprietary bundled browser-client.mjs at runtime; it is not redistributed here. No affiliation with OpenAI. Use at your own risk.