convez.ai
MCP ServerAutomaçãoAvançado
DeliciousBuding

Codex Browser Bridge

DeliciousBuding/codex-browser-bridge

Controle o Chrome do Codex Desktop via MCP para agentes IA

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor 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-bridge

1 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

Estrelas
27
Forks
6
Acompanhando
0
Saúde
85%
Último commit
há 1 dia
Versão
v2.1.0
Issues abertas
1
Contribuidores
3

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-full branch

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

ToolDescription
codex_list_tabsList tabs managed by the current bridge session
codex_create_tabCreate a new browser tab
codex_close_tabClose a browser tab
codex_user_tabsList open tabs across browser windows
codex_claim_tabClaim an existing user tab for automation

Navigation

ToolDescription
codex_navigateNavigate a tab to a URL
codex_navigate_backNavigate a tab back one entry in its history
codex_navigate_forwardNavigate a tab forward one entry in its history
codex_reloadReload a tab
codex_wait_for_loadPoll document.readyState until complete

Page inspection

ToolDescription
codex_screenshotCapture a screenshot (returns MCP image). fullPage is reserved for a future release. The current implementation captures the viewport.
codex_dom_snapshotGet an accessibility tree snapshot
codex_dom_get_visibleGet a simplified visible DOM tree (human-readable; use codex_dom_snapshot for node IDs usable with codex_dom_click)
codex_evaluateEvaluate JavaScript in the page context
codex_get_infoGet backend information from the extension

Interaction

ToolDescription
codex_clickClick an element by CSS selector
codex_fillFill an input by CSS selector
codex_dom_clickClick a DOM node by accessibility node ID from codex_dom_snapshot
codex_cua_clickClick by screen coordinates
codex_cua_typeType text at the current focus
codex_cua_keypressPress keyboard keys
codex_cua_scrollScroll by coordinates

Session

ToolDescription
codex_name_sessionAssign a human-readable name to the browser session
codex_finalizeFinalize 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

  1. The bridge searches for local named pipes matching codex-browser-use-*.
  2. It connects to the selected pipe through go-winio.
  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

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.

Ver o original no GitHub

Bom para

Relacionados