Skip to main content
Glama
Codex Chrome MCP
by ohaoz

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: chrome-devtools-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

Tool

Description

browser_documentation

Full live API reference for browser/tab (read before browser_exec).

browser_exec

Run arbitrary async JS against the API (agent, browser, tabs, user, tab in scope). Full-power escape hatch.

list_user_tabs

List the user's real open Chrome tabs.

list_tabs

List tabs controlled by this session.

new_tab

Create a controlled tab (optionally navigate).

claim_tab

Take control of an existing user tab.

goto

Navigate the active tab to a URL. Auto-restores the previous page if a failed navigation leaves a chrome-error:// page.

snapshot

url + title + node-id DOM (get_visible_dom); warns on chrome-error:// pages.

screenshot

Screenshot the active tab.

click

Click by node_id, selector, text, or x/y.

type_text

Type text (optionally fill a selector).

press_key

Press a key/chord.

scroll

Scroll by delta / into a container (node_id) / wheel at x+y / scrollIntoView a selector. Returns before/after position, pageHeight, nearBottom.

eval_js

Evaluate JS in the page via Playwright's hardened read-only sandbox (no fetch/XHR/DOM writes); warns on chrome-error:// pages.

fetch_url

⚠️ Known-incompatible with the extension backend this bridge targets: tabs.content is marked unsupportedByDefaultIn: extension in the 26.727 API docs, so it fails with browser.tabs.content is not a function. Use Node fetch inside browser_exec (public URLs) or goto + eval_js (authenticated pages) instead.

get_console_logs

Read the tab's console logs.

cdp_send

Send a raw Chrome DevTools Protocol command to the tab or an attached child target (developer mode). See Raw CDP.

cdp_events

Read buffered CDP events with cursor paging ({ cursor, events, hasMore, truncated }). See Raw CDP.

name_session

Name the browser session.

finalize

Clean up session tabs (optionally keep some).

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)

Variable

Default

Purpose

CODEX_CHROME_CLIENT

auto-detected

Absolute path to browser-client.mjs. Auto-detection (cache latest → native-host manifests → newest cache dir) currently resolves 26.715.31925, which has no cdp capability — pin vendor/chrome-26.727.51351/scripts/browser-client.mjs for raw CDP.

CODEX_HOME

~/.codex

Codex home directory.

CODEX_CHROME_BROWSER

extension

Backend id: extension, iab, cdp, or a specific id.

CODEX_CHROME_SECURITY_MODE

disabled-for-local-testing

"" re-enables Codex's consent checks.

CODEX_CHROME_AUTO_APPROVE

true

Auto-approve elicitation prompts.

CODEX_CHROME_SESSION_NAME

🔎 Cursor

Session name shown in the UI.

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.

Available Tools

20 tools
browser_documentationA

Return the full Codex Chrome (browser use) API reference for the live browser/tab object graph. Read this before writing browser_exec code.

Inputs: no named parameters.

browser_execA

Run arbitrary async JavaScript against Codex's Chrome API. In scope: agent, browser, tabs (=browser.tabs), user (=browser.user), tab (current or selected tab, else null), console, log. Use return to produce a JSON result; images returned/emitted are attached. Code runs in the MCP server's Node process: Node APIs like fetch work here (no browser cookies), while in-page JS must go through tab.playwright.evaluate (sandboxed, see eval_js). This is the full-power escape hatch.

Inputs: code (required), tab_id.

cdp_eventsA

Read buffered Chrome DevTools Protocol events from the active tab (or tab_id) via the cdp tab capability. Returns { cursor, events, hasMore, truncated }. Page from each returned cursor with after_sequence while hasMore is true; truncated means older events were evicted. Discover child target selectors from Target.attachedToTarget events. Requires full CDP access enabled.

Inputs: limit, tab_id, methods, target_id, +3 more.

cdp_sendA

Send a raw Chrome DevTools Protocol command to the active tab (or tab_id) via the browser's cdp tab capability, for developer/debugging use. Navigate the tab to its intended http(s) page first; raw CDP is scoped to the tab's current web origin and attaching shows Chrome's 'started debugging' bar. Prefer the higher-level tools for ordinary automation. To observe events for an action, capture a cursor with cdp_events, send the command, then read from that cursor. Requires full CDP access to be enabled (browser/config.toml full_cdp_access_enabled=true).

Inputs: method (required), params, tab_id, target_id, +2 more.

claim_tabA

Take control of one of the user's existing Chrome tabs (id from list_user_tabs) and make it the active tab.

Inputs: id (required).

clickA

Click on the active tab. Prefer node_id (from snapshot) or x+y (viewport coordinates); selector/text use Playwright and may be less reliable when Codex shares the page.

Inputs: x, y, text, tab_id, +2 more.

eval_jsA

Evaluate JavaScript in the page via Playwright and return the result (JSON-projected; depth<=8, strings<=200k chars). Pass an expression or () => ... function source as code; top-level await is allowed. The sandbox is READ-ONLY and stripped: DOM reads, getComputedStyle, and scrolling work, but there is NO fetch/XMLHttpRequest/network, NO DOM mutation, no setInterval, and window only exposes an allowlist - use fetch_url or goto for network data. Warns if the tab is on a chrome-error:// page.

Inputs: code (required), tab_id.

fetch_urlA

Fetch rendered content for one or more URLs through the user's Chrome (their cookies/session) WITHOUT touching the active tab, via browser.tabs.content. Ideal for JSON endpoints (e.g. Discourse /t/.json) or reading pages in bulk - much faster than goto+scroll+DOM scraping. content_type: 'text' (default), 'html', or 'domSnapshot'. May fail if the browser host does not support tabs_content or a content-blocker extension blocks the URL; fall back to goto + eval_js then.

Inputs: urls (required), timeout_ms, content_type.

finalizeA

End browser work for now, cleaning up session tabs. Optionally keep specific tabs open (status 'deliverable' or 'handoff').

Inputs: keep.

get_console_logsC

Return recent console log messages captured for the active tab.

Inputs: limit, tab_id.

gotoA

Navigate the active tab (or tab_id) to a URL. Creates a tab if none is active.

Inputs: url (required), tab_id.

list_tabsA

List tabs currently controlled by this browser session.

Inputs: no named parameters.

list_user_tabsA

List the user's real open Chrome tabs (across windows), newest first. Use an entry's id with claim_tab to take control.

Inputs: no named parameters.

name_sessionB

Set the browser session name (shown in the Codex/Chrome UI).

Inputs: name (required).

new_tabB

Create a new controlled tab (optionally navigate to url) and make it the active tab.

Inputs: url.

press_keyB

Press a key or chord at the current focus, e.g. keys=['Enter'] or ['Control','a'].

Inputs: keys (required), tab_id.

screenshotB

Capture a screenshot of the active tab (or tab_id).

Inputs: tab_id, full_page.

scrollA

Scroll the active tab by a delta (positive scrollY scrolls down). By default scrolls the page reliably regardless of layout; pass node_id to scroll inside a specific scroll container, x+y to send a mouse wheel at a viewport point, or selector to scrollIntoView a specific element. Returns before/after scroll position, pageHeight, and nearBottom. On virtualized lists (e.g. Discourse post streams) use small steps (<= ~2 viewports) and extract between steps, or content will be skipped.

Inputs: x, y, tab_id, node_id, +3 more.

snapshotA

Return the active tab's url, title, and a filtered DOM listing interactable elements with node ids. Use a node_id with the click tool.

Inputs: tab_id.

type_textB

Type text. With selector, fills that element; otherwise types at the current focus (click first to focus).

Inputs: text (required), tab_id, selector.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 20 tools

    Disambiguation4/5

    Most tools are clearly distinct: navigation, interaction, CDP, session management. However, browser documentation, browser_exec, and eval_js have some overlap in the 'run code against browser' space, and list_user_tabs vs list_tabs are subtly different but well-explained. The click/type_text/press_key/scroll interaction tools are well-differentiated.

    Naming Consistency3/5

    There's a mix of conventions: some verb_noun pairs (list_user_tabs, claim_tab, type_text, press_key, fetch_url), some bare verbs (goto, scroll, click, snapshot), and a few camelCase (browser_exec, eval_js, cdp_send, cdp_events). The underscore convention dominates but lacks a uniform verb_noun pattern; the presence of camelCase tools (browser_exec, eval_js, cdp_events) breaks consistency.

    Tool Count4/5

    20 tools is on the higher end but justifiable for a browser automation surface covering navigation, interaction, inspection, DOM access, network fetching, CDP, and session lifecycle. Each tool fills a genuine niche, though some (cdp_send/cdp_events, browser_exec/eval_js) overlap and could arguably be consolidated.

    Completeness4/5

    The surface covers the full browser automation lifecycle: tab management (new/claim/list), navigation (goto), inspection (snapshot, screenshot, console logs), interaction (click, type, keys, scroll), DOM/JS access (eval_js, browser_exec), network (fetch_url), and cleanup (finalize). Minor gaps include no explicit form-submit or file-upload helper, and no tool to close a single specific tab rather than all via finalize, but these are workable via browser_exec.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers