Skip to main content
Glama
Codex Control Chrome MCP

Codex Control Chrome MCP

by iola1999

Codex Control Chrome MCP

npm version CI License: MIT

Expose the Codex Chrome Extension flow to other Agent tools through MCP.

This project lets MCP clients control the user's normal Chrome profile through the installed Codex Chrome Extension. It is useful when an Agent needs existing tabs, cookies, logged-in sessions, installed extensions, screenshots, console/network events, or raw Chrome DevTools Protocol commands.

This is an independent community project. It is not affiliated with OpenAI, Codex, Google, or Chrome.

Platform Support

Platform

Status

Notes

macOS

Tested

Primary supported platform.

Linux

Experimental

Manifest path targets Google Chrome under ~/.config/google-chrome.

Windows

Unsupported

Native Messaging registration uses registry keys on Windows and is not implemented yet.

Node.js 20 or newer is required. npm Trusted Publishing for releases uses Node.js 24 in GitHub Actions.

Related MCP server: chrome-devtools-mcp

Browser Support

Both Chromium browsers use the same Codex extension and the same chrome-extension:// origin, so a single manifest works for either.

Browser

Status

Notes

Google Chrome

Tested

Default target.

Microsoft Edge

Supported

Same extension and native-messaging mechanism; installs to the Edge NativeMessagingHosts directory.

Commands accept --browser <chrome\|edge\|all>. Without the flag, install-native-host installs for every supported browser whose profile directory exists, uninstall-native-host targets every browser it previously installed for, and status reports both.

Quick Start

Install and enable the Codex Chrome Extension in the Chrome or Edge profile you want to automate.

Install the package globally, then register the native host (auto-detects the browsers present):

npm install -g codex-control-chrome-mcp
codex-control-chrome-mcp install-native-host

A global install gives the native host a stable path, so its launcher execs Node directly against the installed CLI with no per-connection npx cost. To target one browser explicitly:

codex-control-chrome-mcp install-native-host --browser edge

Configure your Agent to use the MCP stdio server through the installed binary:

{
  "type": "stdio",
  "command": "codex-control-chrome-mcp",
  "args": ["--stdio"],
  "startup_timeout_sec": 30
}

If your MCP client does not inherit a shell PATH that includes npm's global bin directory (common for GUI apps), use the absolute path from npm prefix -g — for example /opt/homebrew/bin/codex-control-chrome-mcp — as command.

Check status and uninstall:

codex-control-chrome-mcp status
codex-control-chrome-mcp uninstall-native-host   # restores the previous Codex native host manifest

Without a global install

npx -y codex-control-chrome-mcp@latest <command> still works for every command. Be aware that npx … install-native-host writes a launcher that re-runs npx on every extension connection; a cold or evicted npx cache can add seconds and may exceed the extension's connect timeout (the bridge then looks stuck "not connecting"). The installer detects the npx temp copy and keeps that launcher as a fallback — install globally and re-run install-native-host for the fast, stable path.

Agent Skill

If your Agent supports skills, install or reference the bundled skill folder:

skills/codex-control-chrome-mcp

The skill documents the recommended MCP tool order for:

  • status checks

  • tab listing and claiming

  • CDP attach and command execution

  • screenshots

  • network and console event reads

  • tab finalization

Security Notes

This project controls the user's normal Chrome profile. MCP clients connected to it can inspect page contents and send raw CDP commands to claimed tabs.

Only install and run it on machines and Chrome profiles you own or are explicitly authorized to automate. Do not send browser cookies, password stores, profile databases, tokens, or private session files in issues or logs.

See SECURITY.md for the security model and reporting process.

How It Works

The Codex Chrome Extension does not need an external Chrome remote debugging port. It uses Chrome Native Messaging and the extension's chrome.debugger permission:

Chrome extension
  -> chrome.runtime.connectNative("com.openai.codexextension")
  -> codex-control-chrome-mcp native host
  -> local MCP bridge socket
  -> chrome.debugger.attach / chrome.debugger.sendCommand
  -> CDP

Because the control entrypoint is inside the normal Chrome profile, existing cookies, logged-in sessions, tabs, and extensions can be reused.

Read more:

Development

Install dependencies:

npm ci

Run checks:

npm run ci

Run the MCP server locally:

node ./bin/codex-control-chrome-mcp.js --stdio

Run native host mode locally for development:

node ./bin/codex-control-chrome-mcp.js --native-host

Troubleshooting

A Codex update stopped the bridge

Codex App/extension updates re-register their own com.openai.codexextension native-messaging manifest, which overwrites this project's proxy registration (the bundled host binary has even been renamed across releases). The symptom is status showing sockets: [], registered: false, and a manifest path back inside the Codex bundle.

The MCP stdio server now self-heals: on startup it re-asserts the manifest when it detects it was reverted, so you usually do not need to re-run install-native-host. Because Chrome only reads the manifest when the extension reconnects, reload the Codex Chrome Extension (or restart Chrome) once after a Codex update to bring the bridge back. Set CODEX_CONTROL_CHROME_NO_AUTO_REGISTER=1 to disable the auto re-register.

If Codex App integration stops working, uninstall this native host to restore the backed-up manifest:

npx -y codex-control-chrome-mcp@latest uninstall-native-host

If tab or CDP tools fail, use the bundled skill workflow: list tabs again, claim only current tab IDs, attach before raw CDP calls, and read CDP events after enabling the relevant domain.

"Debugger is not attached" / flaky CDP under concurrency

CDP tools self-heal a stale debugger attachment since 1.4.0 (attach is verified, and a lost attachment is recovered with detach → re-attach → retry). If you still see attach flakiness — most likely when several browser-control stacks share one Chrome and contend for the single debugger per tab — see the Troubleshooting & Debugging Playbook for the root cause, reference points (official client, extension service worker), and the scripts/concurrency-check.mjs soak test.

See Install And Uninstall for the full per-browser checklist (the registered flag and host classification).

License

MIT

Available Tools

16 tools
chrome_attach_tabC

Attach Chrome debugger to a claimed tab.

Inputs: tabId (required).

chrome_bridge_statusB

Ask the active Codex Control Chrome MCP bridge for status.

Inputs: no named parameters.

chrome_cdp_sendC

Send a raw CDP command to a claimed and attached tab.

Inputs: tabId (required), method (required), params, timeoutMs.

chrome_claim_tabC

Claim an existing Chrome tab by numeric tab id.

Inputs: tabId (required).

chrome_create_tabA

Create a new background tab and claim it for this MCP session.

Inputs: no named parameters.

chrome_detach_tabC

Detach Chrome debugger from a claimed tab.

Inputs: tabId (required).

chrome_evaluateC

Evaluate JavaScript in a claimed tab using Runtime.evaluate.

Inputs: tabId (required), expression (required), awaitPromise.

chrome_finalize_tabsC

Finalize claimed tabs. Use status handoff or deliverable.

Inputs: keep.

chrome_get_infoB

Get connected Codex Chrome extension backend info.

Inputs: no named parameters.

chrome_name_sessionC

Set the Chrome tab group/session name.

Inputs: name.

chrome_navigateC

Navigate a claimed tab to a URL using CDP Page.navigate.

Inputs: url (required), tabId (required).

chrome_read_eventsB

Read and clear CDP/download notifications buffered by this MCP process.

Inputs: limit, method.

chrome_screenshotC

Capture a screenshot from a claimed tab. Returns base64 PNG.

Inputs: tabId (required), format.

chrome_session_tabsA

List tabs currently claimed by this MCP browser session.

Inputs: no named parameters.

chrome_statusB

Show native host manifest paths and discovered bridge sockets.

Inputs: no named parameters.

chrome_user_tabsA

List user Chrome tabs visible to the extension.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 16 tools

    Disambiguation3/5

    The status/info trio (chrome_status, chrome_bridge_status, chrome_get_info) overlaps heavily — all report diagnostic state, and the distinction between 'native host manifest paths', 'bridge status', and 'extension backend info' is subtle enough that an agent may pick the wrong one. The tab tools (user_tabs vs session_tabs, create vs claim vs attach) are reasonably distinct once the descriptions are read.

    Naming Consistency4/5

    All names use a consistent chrome_ prefix and snake_case, and most follow verb_noun (chrome_create_tab, chrome_claim_tab, chrome_navigate). Minor deviations: noun-only names (chrome_status, chrome_bridge_status) and one verb-last (chrome_cdp_send).

    Tool Count4/5

    16 tools is slightly heavy but justified by the layered surface: host/bridge diagnostics, session and tab lifecycle, debugger attach/detach, CDP escape hatch, and high-level navigate/evaluate/screenshot helpers. Each tool maps to a real step in the workflow.

    Completeness4/5

    The lifecycle is well covered: discover, name session, create/claim tabs, attach/detach debugger, drive via CDP, evaluate, screenshot, read events, and finalize. Minor gaps: no explicit tab close/release tool, no wait-for-load or focus/activate operation, and no dedicated input (click/type) helper beyond raw chrome_cdp_send.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Lets coding agents control and inspect a live Chrome browser via MCP, providing Chrome DevTools capabilities for automation, debugging, and performance analysis.
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Exposes Codex's Chrome plugin as an MCP server, enabling MCP clients to drive a real, logged-in Chrome browser by navigating, snapshotting the DOM, clicking, typing, taking screenshots, running Playwright, and sending raw CDP commands.
      20
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables local opencode agents to control a live Chrome browser via MCP tools, including tab management, JavaScript execution, clicking, form filling, page reading, screenshots, and console log retrieval.
      3
      MIT