Codex Browser Bridge
DeliciousBuding/codex-browser-bridge
Controle o Chrome do Codex Desktop via MCP para agentes IA
Ver no GitHubServidor MCP que expõe a ponte de navegador Chrome do Codex Desktop, permitindo que Claude Code e outros agentes controlem abas, capturem screenshots, leiam o DOM e executem ações no navegador. Reutiliza a sessão Chrome existente sem copiar perfis de navegador.
Instalação
npx convez-ai DeliciousBuding/codex-browser-bridge1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de navegação em dashboards e aplicações web
- Captura de screenshots e snapshots do DOM para análise
- Interação com plataformas que requerem sessão autenticada
- Debugging e testes de desenvolvimento web local
Veredito

Ferramenta especializada para Windows que integra Codex Desktop com MCP, possibilitando automação real de navegador. Maduro (v1.6.0) mas com escopo limitado a ambiente local Codex — ideal para fluxos de automação web que dependem de contexto autenticado.
README
A tradução para o português deste README ainda está na fila.
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.6.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 1.6.x line moves the bridge binary to Rust. Tagged releases through v1.5.4 use Go-built Windows binaries; 1.6.x builds Rust x64 and arm64 release assets after CI and tag validation.
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
- Go 1.23+ if building from source
- Rust 1.85+ if building the
rewrite/rust-fullbranch
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
Option 1: Install with npm
npm i -g @delicious233/codex-browser-bridge
Option 2: Install with Go
go install github.com/DeliciousBuding/codex-browser-bridge/cmd/bridge@latest
Make sure your Go binary path is available in PATH.
Option 3: Download a release
Download the latest binary from:
https://github.com/DeliciousBuding/codex-browser-bridge/releases
Then place codex-browser-bridge.exe somewhere in your PATH.
Option 4: Build from source
Current release build:
git clone https://github.com/DeliciousBuding/codex-browser-bridge.git
cd codex-browser-bridge
make build
The binary will be generated at:
bin/codex-browser-bridge.exe
Rust rewrite branch build:
git checkout rewrite/rust-full
cargo check --locked
cargo test --locked
cargo build --locked --release
The Rust binary will be generated at:
target/release/codex-browser-bridge.exe
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
| Tool | Description |
|---|---|
codex_list_tabs | List tabs managed by the current bridge session |
codex_create_tab | Create a new browser tab |
codex_close_tab | Close a browser tab |
codex_user_tabs | List open tabs across browser windows |
codex_claim_tab | Claim an existing user tab for automation |
Navigation
| Tool | Description |
|---|---|
codex_navigate | Navigate a tab to a URL |
codex_navigate_back | Navigate a tab back one entry in its history |
codex_navigate_forward | Navigate a tab forward one entry in its history |
codex_reload | Reload a tab |
codex_wait_for_load | Poll document.readyState until complete |
Page inspection
| Tool | Description |
|---|---|
codex_screenshot | Capture a screenshot (returns MCP image). fullPage is reserved for a future release. The current implementation captures the viewport. |
codex_dom_snapshot | Get an accessibility tree snapshot |
codex_dom_get_visible | Get a simplified visible DOM tree (human-readable; use codex_dom_snapshot for node IDs usable with codex_dom_click) |
codex_evaluate | Evaluate JavaScript in the page context |
codex_get_info | Get backend information from the extension |
Interaction
| Tool | Description |
|---|---|
codex_click | Click an element by CSS selector |
codex_fill | Fill an input by CSS selector |
codex_dom_click | Click a DOM node by accessibility node ID from codex_dom_snapshot |
codex_cua_click | Click by screen coordinates |
codex_cua_type | Type text at the current focus |
codex_cua_keypress | Press keyboard keys |
codex_cua_scroll | Scroll by coordinates |
Session
| Tool | Description |
|---|---|
codex_name_session | Assign a human-readable name to the browser session |
codex_finalize | Finalize the session and clean up tabs |
Architecture
MCP Client
Claude Code / other agent
│
│ stdio JSON-RPC
▼
codex-browser-bridge
Go 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
- The bridge searches for local named pipes matching
codex-browser-use-*. - It connects to the selected pipe through
go-winio. - Every request is encoded as a 4-byte little-endian length prefix followed by a JSON-RPC payload.
- Browser operations are sent to the Codex extension host.
- Page-level operations use Chrome DevTools Protocol commands such as
Page.navigate,Page.captureScreenshot,Runtime.evaluate, andInput.dispatchMouseEvent. - 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 discoverworks 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
make test
make build
Common commands:
make build # build binary
make test # go vet ./... && go test ./...
make clean # remove build output
cargo check --locked
cargo test --locked
cargo build --locked --release
See docs/rust-rewrite/npm-ci-plan.md for the Rust rewrite npm and CI plan.
Roadmap
Planned or open work:
- clearer error messages for common pipe / extension failures
- non-Windows fallback or explicit platform guards
- screenshot output handling across MCP clients
- typed tool result schemas
- optional allowlist / confirmation layer for sensitive domains
- examples for Claude Code, Cursor, Codex CLI, and other MCP clients
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.