# Codex Browser Bridge

> Expose Codex Desktop's Chrome browser bridge as an MCP server for Claude Code and other agents.

- **Type:** MCP server
- **Install:** `agentstack add mcp-deliciousbuding-codex-browser-bridge`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [DeliciousBuding](https://agentstack.voostack.com/s/deliciousbuding)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [DeliciousBuding](https://github.com/DeliciousBuding)
- **Source:** https://github.com/DeliciousBuding/codex-browser-bridge
- **Website:** https://github.com/DeliciousBuding/codex-browser-bridge

## Install

```sh
agentstack add mcp-deliciousbuding-codex-browser-bridge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

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

Or download from [GitHub Releases](https://github.com/DeliciousBuding/codex-browser-bridge/releases).

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

## 30-Second Setup (Claude Code)

Add to your Claude Code MCP settings:

```json
{
  "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:

```bash
# 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 |
| `codex_drag` | CDP mouse drag (sliders, sortable lists) |
| `codex_cua_click` | Click at exact coordinates (CDP mouse events) |
| `codex_cua_type` | Type text at current focus |
| `codex_cua_keypress` | Press key sequence (Enter, Ctrl+C, etc.) |
| `codex_cua_scroll` | Scroll at coordinates by delta |
| `codex_click_and_wait` | Click + wait for load (1 call) |
| `codex_form_fill` | Fill multiple fields from `{selector: value}` map |
| `codex_file_input` | 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

```bash
# 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

```bash
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](https://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](https://github.com/DeliciousBuding)
- **Source:** [DeliciousBuding/codex-browser-bridge](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-deliciousbuding-codex-browser-bridge
- Seller: https://agentstack.voostack.com/s/deliciousbuding
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.