Codex Browser Bridge

codex-browser-bridge

Let Claude Code and other MCP agents control your existing Chrome browser through Codex Desktop's browser bridge. 52 MCP tools. Pure Rust. Single binary. Zero config.

中文

---

What It Does

codex-browser-bridge turns your local Codex Desktop + Chrome into an MCP server that any agent can control.

No browser profile copying. No WebDriver. No remote setup. It connects to the Codex browser named pipe that already exists on your machine, speaks the same JSON-RPC protocol, and exposes 52 MCP tools for browser automation.

Your agent can:

• Open, close, and switch browser tabs
• Navigate pages, go back/forward, wait for loads
• Capture screenshots (viewport PNG)
• Read DOM / accessibility trees (including ARIA role+name search)
• Click, type, scroll — via CSS selectors, coordinates, or accessibility node IDs
• Execute arbitrary JavaScript in the page context
• Upload files to `` elements
• Handle JavaScript dialogs (alert / confirm / prompt)
• Read and set browser cookies
• Run raw CDP commands (Chrome DevTools Protocol escape hatch)
• Self-diagnose with codex_doctor

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

Quick Install

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

Or download from GitHub Releases.

Requires: Windows · Chrome · Codex Desktop · Codex Chrome Extension

30-Second Setup (Claude Code)

Add to your Claude Code MCP settings:

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

Restart Claude Code. Then ask:

List my open browser tabs.
Open https://example.com and take a screenshot.
Find the login button and click it.

For Cursor, OpenClaw, Hermes Agent — see [examples/](examples/).

3. Install the agent skill (recommended)

The npm package includes a skill that teaches agents how to use all 52 tools effectively. After install, copy it to your skills directory:

# Global install → Claude Code skills
cp -r "$(npm root -g)/@delicious233/codex-browser-bridge/skills/codex-browser" ~/.claude/skills/

# Or into a local project
cp -r node_modules/@delicious233/codex-browser-bridge/skills/codex-browser .claude/skills/

👤 For agents reading this: to self-install, run the copy command above against your own skills directory. The skill is at skills/codex-browser/SKILL.md inside the installed npm package.

All 52 MCP Tools

Tab Management [Tabs]

| Tool | Description | |------|-------------| | codex_list_tabs | List tabs owned by this session | | codex_create_tab | Create a new blank tab | | codex_close_tab | Close a tab by ID | | codex_user_tabs | List all browser tabs (including unclaimed) | | codex_claim_tab | Claim an existing user tab |

Navigation [Navigation]

| Tool | Description | |------|-------------| | codex_navigate | Navigate to URL | | codex_reload | Reload current page | | codex_navigate_back | Go back one history entry | | codex_navigate_forward | Go forward one history entry | | codex_wait_for_load | Poll document.readyState until complete | | codex_nav_and_wait | Navigate + wait (1 call instead of 2) | | codex_wait_for_element | Poll a CSS selector until it matches (SPAs) | | codex_wait_for_url | Poll until URL contains a substring (SPA routes) |

DOM & Accessibility [DOM]

| Tool | Description | |------|-------------| | codex_dom_snapshot | Full accessibility tree with node IDs | | codex_dom_get_visible | Human-readable visible DOM tree | | codex_dom_click | Click by accessibility node ID | | codex_find_element | Find elements by ARIA role + name | | codex_click_element | Click element from codex_find_element result |

Page Inspection [Page]

| Tool | Description | |------|-------------| | codex_get_url | Current tab URL | | codex_get_title | Current page title | | codex_evaluate | Execute JavaScript, return JSON result | | codex_page_assets | List page resources (images, CSS, JS, fonts) | | codex_console_logs | Capture console output for a window | | codex_emulate_device | Emulate mobile viewport (reset=true to clear) | | codex_screenshot | Capture viewport PNG screenshot | | codex_screenshot_element | Capture a single element by selector | | codex_print_pdf | Render page to PDF | | codex_bring_to_front | Activate a background tab (fixes screenshot timeouts) | | codex_dialog | Handle alert / confirm / prompt | | codex_performance_metrics | DOM nodes, JS heap, event listeners (Performance) |

Input & Interaction [Input]

| Tool | Description | |------|-------------| | codex_click | Click by CSS selector (JS click) | | codex_fill | Fill input by CSS selector | | codex_hover | Hover over element (dropdowns, tooltips) | | codex_select_option | Set ` value + fire change | | codexdrag | CDP mouse drag (sliders, sortable lists) | | codexcuaclick | Click at exact coordinates (CDP mouse events) | | codexcuatype | Type text at current focus | | codexcuakeypress | Press key sequence (Enter, Ctrl+C, etc.) | | codexcuascroll | Scroll at coordinates by delta | | codexclickandwait | Click + wait for load (1 call) | | codexformfill | Fill multiple fields from {selector: value} map | | codexfileinput | Upload files to ` |

Network [Network]

| Tool | Description | |------|-------------| | codex_network_cookies | Read cookies (values redacted by default) | | codex_network_set_cookie | Set a browser cookie | | codex_delete_cookies | Delete cookies by name | | codex_storage | Get/set localStorage | | codex_network_monitor | Pair request↔response into structured list |

CDP Escape Hatch [CDP]

| Tool | Description | |------|-------------| | codex_execute_cdp | Execute any CDP command (allowlist-protected) |

Session [Session]

| Tool | Description | |------|-------------| | codex_name_session | Name the current session | | codex_finalize | Clean up tabs, release resources | | codex_get_info | Get extension backend metadata | | codex_doctor | Self-diagnostics (pipe health, latency, version) |

CLI Usage

# MCP mode (default)
codex-browser-bridge --mode mcp

# List active pipes
codex-browser-bridge --mode discover

# Interactive REPL for debugging
codex-browser-bridge --mode cli

# With tool profiles
codex-browser-bridge --mode mcp --profile basic     # 33 tools
codex-browser-bridge --mode mcp --profile network   # 50 tools
codex-browser-bridge --mode mcp --profile full      # all 52 (default)

Architecture

MCP Client (Claude Code / Cursor / OpenClaw)
        │ stdio JSON-RPC
        ▼
codex-browser-bridge (Rust binary)
        │ length-prefixed JSON-RPC frames
        ▼
Windows Named Pipe \\.\pipe\codex-browser-use-*
        │
        ▼
Codex Desktop → Chrome Extension → Chrome tabs

Security

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

• Never expose to a network port
• Only run for trusted MCP clients
• Review agent actions before allowing sensitive operations
• Avoid using on pages with passwords, payments, or admin consoles
• Redact tab titles, URLs, DOM text, screenshots before sharing output
• codex_file_input enforces path traversal prevention (canonicalize + prefix check, 10 MB limit)
• Cookie values redacted by default; CDP allowlist blocks dangerous domains

Development

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

cargo check --locked
cargo test --locked
cargo clippy --locked -- -D warnings
cargo build --locked --release

Source layout:

src/
  mcp/          MCP server (mod, types, schema, handlers, profiles)
  browser.rs    CDP + browser operations
  client.rs     Named pipe transport + sticky attach
  security.rs   URL + file path validation
  doctor.rs     Pipe diagnostics
  cli.rs        Interactive debug REPL
  discovery.rs  Pipe auto-discovery
  protocol.rs   Length-prefixed JSON-RPC frames

Roadmap

See [ROADMAP.md](ROADMAP.md). Highlights:

• codex_network_monitor — request/response inspection
• codex_emulate_device — mobile viewport emulation
• codex_storage — localStorage / sessionStorage access
• v2.0.0: Cross-platform (macOS / Linux via Unix domain sockets)

Related

• [examples/](examples/) — MCP configs for Claude Code, Cursor, OpenClaw, Hermes Agent
• [skills/codex-browser/](skills/codex-browser/SKILL.md) — Agent skill (LLM usage guide)
• [ROADMAP.md](ROADMAP.md) — Full roadmap with SUPER scores
• [CHANGELOG.md](CHANGELOG.md) — Release history
• [CONTRIBUTING.md](CONTRIBUTING.md) — Dev setup and conventions

License

MIT. Maintained independently from Codex / Anthropic / Google.

Acknowledgments

Thanks to LINUX DO for community support and feedback.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DeliciousBuding
• Source: DeliciousBuding/codex-browser-bridge
• License: MIT
• Homepage: https://github.com/DeliciousBuding/codex-browser-bridge

Install and usage instructions live in the source repository linked above.