Codex Chrome MCP
Coordinate a real, logged-in Chrome browser from MCP clients (like Cursor or Claude Code) using Codex’s Chrome plugin. Capabilities include:
Tab & session management — list user‑controlled tabs, open new tabs, claim existing ones, navigate to URLs, and finalize sessions.
Page interaction — click elements (by node ID, selector, text, or coordinates), type, press keys, scroll, and capture viewport/full‑page screenshots.
DOM inspection — snapshot the DOM with interactable node IDs; fetch rendered content from a URL using the browser’s session cookies (
fetch_url); read console logs.Code execution — run sandboxed, read‑only JavaScript in the page (
eval_js) or execute full‑power async Node.js scripts with access to the browser API (browser_exec), including Node’sfetchfor arbitrary HTTP requests.Raw DevTools (CDP) — send arbitrary Chrome DevTools Protocol commands and read buffered events for advanced debugging, network interception, profiling, and breakpoints (requires compatible client).
API reference — retrieve the live documentation for the browser/tab object graph.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Codex Chrome MCP Navigate to my Gmail inbox and take a screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 tabsThis 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'sbrowser-client.mjsmust exist under~/.codex/plugins/cache/openai-bundled/chrome/…, or use the vendored client undervendor/(required for raw CDP, see below).A live
codex-browser-usepipe — 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 |
| Full live API reference for |
| Run arbitrary async JS against the API ( |
| List the user's real open Chrome tabs. |
| List tabs controlled by this session. |
| Create a controlled tab (optionally navigate). |
| Take control of an existing user tab. |
| Navigate the active tab to a URL. Auto-restores the previous page if a failed navigation leaves a |
| url + title + node-id DOM ( |
| Screenshot the active tab. |
| Click by node_id, selector, text, or x/y. |
| Type text (optionally fill a selector). |
| Press a key/chord. |
| Scroll by delta / into a container ( |
| Evaluate JS in the page via Playwright's hardened read-only sandbox (no fetch/XHR/DOM writes); warns on |
| ⚠️ Known-incompatible with the |
| Read the tab's console logs. |
| Send a raw Chrome DevTools Protocol command to the tab or an attached child target (developer mode). See Raw CDP. |
| Read buffered CDP events with cursor paging ( |
| Name the browser session. |
| 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:
A 26.727+ browser-client: only 26.727+ injects the
cdptab capability (the plugin cache currently ships26.715.31925, which lacks it). This repo vendors a working client atvendor/chrome-26.727.51351/; pointCODEX_CHROME_CLIENTat itsscripts/browser-client.mjsand keep thescripts/anddocs/siblings together (elsebrowser_documentationbreaks).full_cdp_access_enabled = truein~/.codex/browser/config.toml— the client's full-CDP gate reads it through the shim'snodeRepl.configsurface (src/runtime.ts).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_sendauto-attaches the debugger extension-side; Chrome shows its "started debugging" bar. Event domains (Page,Network, …) emit nothing until their.enablecommand is sent.To observe events for an action: take a cursor with
cdp_events, perform the action, then read from that cursor withafter_sequence; page whilehasMoreis true (truncatedmeans older events were evicted; reuse the same filters while paging).Child targets (iframes, workers): discover selectors from
Target.attachedToTargetevents, then passsession_idortarget_id.
Guardrails enforced upstream (some commands are refused with guidance):
No top-level
Documentinterception — intercept sub-resources or page-initiated requests instead.Fetch.enablepatterns must name an explicit non-DocumentresourceType(XHR,Fetch,Script, …); an unscoped pattern implicitly includesDocumentand is rejected.No
Fetch.disable— clear interception withFetch.enable({ patterns: [] }).Breakpoints: a pause blocks the
Runtime.evaluatethat triggered it. Trigger fire-and-forget (awaitPromise: false, or wrap insetTimeout(fn, 0)), then pollDebugger.paused, inspect withDebugger.evaluateOnCallFrame, andDebugger.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 |
| auto-detected | Absolute path to |
|
| Codex home directory. |
|
| Backend id: |
|
|
|
|
| Auto-approve elicitation prompts. |
|
| 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-usepipe (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 toolsbrowser_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
Scored across 20 tools
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.
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.
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.
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
Related MCP Connectors
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Related MCP Servers
- AlicenseBqualityBmaintenanceExposes the Codex Chrome extension flow to other Agent tools through MCP, enabling Chrome automation via CDP and tab management.1673 npm12MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to control and inspect a live Chrome browser via MCP, including performance tracing, network and console debugging, screenshots, and reliable Puppeteer-based automation.2,494,666 npmApache 2.0
- AlicenseBqualityCmaintenanceExposes a live Chrome browser to any MCP client through a single local endpoint, enabling real-tab control, DOM interaction, cookies and session use, network/console capture, PDF export, and CDP-powered debugging.28MIT
- AlicenseAqualityCmaintenanceEnables any MCP-capable agent to drive a real Chrome browser through stdio or HTTP, supporting navigation, page reading, interaction, scrolling, JavaScript execution, and replaying saved step-by-step recipes.24Apache 2.0