codex-browser-bridge

Let Claude Code and other MCP agents control your existing Chrome browser through Codex Desktop's browser bridge.

中文

codex-browser-bridge exposes Codex Desktop's Chrome browser bridge as an MCP server.

It connects to the local Codex browser named pipe, speaks the same length-prefixed JSON-RPC protocol, and provides browser-control tools to Claude Code or any MCP-compatible agent.

Why

Codex Desktop can talk to its Chrome extension through a privileged native pipe. Other agents, such as Claude Code, cannot directly access that internal bridge.

This project reuses the local browser bridge that already exists on your machine and wraps it as an MCP server.

That means an agent can:

• inspect your current browser tabs
• claim an existing tab
• open and close tabs
• navigate pages
• capture screenshots
• read DOM / accessibility snapshots
• click, type, scroll, and evaluate JavaScript

Useful when an agent needs to work with pages that require a real browser session, such as dashboards, logged-in web apps, local development servers, or documentation sites.

Status

Version 1.7.0 is a local Windows tool for Codex Desktop and the Codex Chrome Extension. It supports both known Codex browser pipe name formats:

• codex-browser-use-<uuid>
• codex-browser-use\<uuid>

Run the bridge for local development and controlled automation on a single trusted machine.

The bridge binary is pure Rust. Tagged releases build x64 and arm64 Windows binaries, published to GitHub Releases and npm.

Features

• MCP server over stdio
• Single Windows binary
• No browser profile copying
• Uses your existing Chrome session
• Auto-discovers codex-browser-use-* named pipes
• Talks to Codex Desktop's extension host through JSON-RPC
• Uses Chrome DevTools Protocol commands for page control
• Includes an interactive CLI mode for debugging

Requirements

• Windows
• Chrome
• Codex Desktop running
• Codex Chrome Extension installed and enabled
• Rust 1.85+

The bridge connects to local named pipes created by Codex Desktop. If no pipe is found, start Codex Desktop first and make sure the extension is active.

Installation

Recommended: npm

npm i -g @delicious233/codex-browser-bridge

Alternative: Download a release

https://github.com/DeliciousBuding/codex-browser-bridge/releases

Download codex-browser-bridge.exe and place it somewhere in your PATH.

Alternative: Build from source

git clone https://github.com/DeliciousBuding/codex-browser-bridge.git
cd codex-browser-bridge
cargo build --locked --release

Quick Start with Claude Code

Add the MCP server to your Claude Code settings.

{
  "mcpServers": {
    "codex-browser": {
      "command": "codex-browser-bridge",
      "args": ["-mode", "mcp"],
      "transport": "stdio"
    }
  }
}

If you built from source, use the absolute path instead:

{
  "mcpServers": {
    "codex-browser": {
      "command": "D:/path/to/codex-browser-bridge/bin/codex-browser-bridge.exe",
      "args": ["-mode", "mcp"],
      "transport": "stdio"
    }
  }
}

Restart Claude Code after editing the settings file.

Then ask the agent things like:

List my open browser tabs.

Open https://example.com in a new tab and take a screenshot.

Claim my current documentation tab and summarize what is visible.

CLI Usage

The binary has three modes.

MCP mode

Default mode. Used by Claude Code or other MCP clients.

codex-browser-bridge -mode mcp

Discover mode

Lists active Codex browser named pipes.

codex-browser-bridge -mode discover

Example output:

[
  {
    "Name": "codex-browser-use-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "UUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
]

Interactive CLI mode

Useful for debugging the bridge without an MCP client.

codex-browser-bridge -mode cli

Connect to a specific pipe:

codex-browser-bridge -mode cli -pipe "codex-browser-use-<uuid>"

Available CLI commands:

tabs
create
close <tab_id>
user-tabs
claim <tab_id>
nav <tab_id> <url>
snapshot <tab_id>
screenshot <tab_id>
info
ping
try <method> [json_params]
quit

CLI output can include pipe IDs, tab titles, full URLs, screenshots, and page text from logged-in tabs. Redact that output before posting bug reports or feature requests.

MCP Tools

Tab management

Navigation

Page inspection

Interaction

Session

CDP & Network (new in v1.7.0)

Architecture

MCP Client
  Claude Code / other agent
        │
        │ stdio JSON-RPC
        ▼
codex-browser-bridge
  Rust binary
        │
        │ length-prefixed JSON-RPC frames
        ▼
Windows Named Pipe
  \\.\pipe\codex-browser-use-*
        │
        ▼
Codex Desktop extension host
        │
        ▼
Codex Chrome Extension
        │
        ▼
Chrome tabs

How It Works

1. The bridge searches for local named pipes matching codex-browser-use-*.
2. It connects to the selected pipe through the Windows named pipe API.
3. Every request is encoded as a 4-byte little-endian length prefix followed by a JSON-RPC payload.
4. Browser operations are sent to the Codex extension host.
5. Page-level operations use Chrome DevTools Protocol commands such as Page.navigate, Page.captureScreenshot, Runtime.evaluate, and Input.dispatchMouseEvent.
6. The MCP layer exposes these operations as codex_* tools.

Security Notes

This tool gives an agent access to your active browser session.

Use it with the same caution you would apply to browser automation tools:

• do not expose the bridge to a network port
• do not run it for untrusted MCP clients
• review agent actions before allowing sensitive operations
• avoid using it on pages containing passwords, payment details, private tokens, or production admin consoles
• remember that claimed tabs may already be logged in
• redact tab titles, URLs, DOM text, screenshots, pipe IDs, and debug logs before sharing output

The project is intended for local development and controlled automation.

Troubleshooting

No pipe found

No codex-browser-use pipes found. Is Codex Desktop running?

Check:

• Codex Desktop is running
• Chrome is running
• Codex Chrome Extension is installed and enabled
• the extension has been initialized by Codex Desktop

Claude Code does not show the tools

Check:

• the binary is in PATH
• the MCP server config points to the correct executable
• Claude Code was restarted after editing settings
• codex-browser-bridge -mode discover works in a terminal

CDP command fails

Some browser operations require the bridge to attach to the tab before sending CDP commands. If a tab was opened outside the bridge, list user tabs first, then claim the target tab.

Development

git clone https://github.com/DeliciousBuding/codex-browser-bridge.git
cd codex-browser-bridge

cargo check --locked          # fast check
cargo test --locked            # run all tests
cargo clippy --locked -- -D warnings  # lint
cargo build --locked --release # release build → target/release/codex-browser-bridge.exe

Roadmap

See ROADMAP.md for the full project roadmap. Highlights:

• codex_fullpage_screenshot — true full-page capture via CDP clip + scroll compose
• codex_network_monitor — request/response inspection via Network.enable
• codex_emulate_device — mobile viewport emulation
• Non-Windows transport abstraction (WSL / Unix socket fallback)

License

MIT License.

Project Relationship

Maintained independently from OpenAI, Codex Desktop, Anthropic, Claude Code, Google, and Chrome.

Acknowledgments

Thanks to LINUX DO for the community support and feedback.