Power your agent
Yayıncıdan kurulum. PlugMCP uç noktası değildir.
Host a copy with our keys and logs.
Registry'de henüz paketlenmiş bir sürüm yok. Deponun README dosyasını izleyin.
Uzak URL mi, yoksa makinenizde bir komut mu? İki kurulum arasındaki fark
PlugMCP’de çalıştır
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
BaşlatYayıncıdan
codex-browser-bridge turns your local ChatGPT desktop app + browser extension into an MCP server that any agent can control.
No browser profile copying. No WebDriver. No remote setup. It discovers the
codex-browser-use local transports that already exist on your machine, identifies
each live browser-extension instance, speaks the same JSON-RPC protocol, and
exposes 66 MCP tools for browser automation.
Expose the ChatGPT desktop app's browser bridge (formerly Codex Desktop) as an MCP server — drive Chrome and Edge from Claude Code and other agents.
This README describes v2.0.0: 66 MCP tools (basic 46 / network 65 /
full 66), distributed as Windows and Linux GNU packages.
Upgrading from 1.x? Read the upgrade guide before updating an installation that uses saved continuation files or numeric-only tab claims.
The goal is complete browser capability access for non-Codex agents. Coverage is tracked by method and semantics in the parity matrix; a tool count or an alternative CLI does not establish full parity. App-private services and remaining locator differences are explicitly recorded there.
Naming note: OpenAI now documents this surface as the ChatGPT browser extension. The underlying
codex-browser-usepipe and JSON-RPC method names still use the Codex-era identifiers, so this project keeps itscodex_*tool surface for compatibility.
Your agent can:
<input type=file> elementscodex_doctorUseful when an agent needs to work with pages that require a real browser session — dashboards, logged-in web apps, local dev servers, documentation sites.
Claude Code plugin (recommended):
claude plugin install codex-browser --marketplace DeliciousBuding/codex-browser-bridge
The plugin fetches the pinned npm package and platform binary through npx on
first use. A global npm install is optional.
Standalone CLI or manual MCP configuration:
npm i -g @delicious233/codex-browser-bridge
Or download the binary from GitHub Releases.
Requires: a local supported extension transport · Node.js 18+ for the npm/npx path · a supported Chromium browser · ChatGPT desktop app/browser-extension service
Last live verification: 2026-10-24 with ChatGPT desktop app (OpenAI.Codex
package) 26.1016.8120.0 and Edge extension 1.26.1020.11845.
The 2026-10-24 Windows Edge and Linux arm64 Chrome runs passed the 20-check parity smoke and the 9-check observation/locator/file-result smoke. File chooser capture and permission-denial cleanup passed; successful file upload requires the extension's file-access permission and was not accepted in these runs. | macOS | Unix code compilation alone does not establish runtime support; no published binary or live verification |
The bridge does not install a second browser extension or copy your browser profile. One MCP server session controls one browser-extension instance at a time; tabs from multiple browser profiles are not merged into a single list.
Linux source discovers CODEX_BRIDGE_SOCKET_DIR when set, otherwise
$XDG_RUNTIME_DIR/codex-browser-use, then /tmp/codex-browser-use. It checks
private socket ownership/permissions and peer UID, and accepts the official
shared sticky directory mode 1777 with socket mode 0600. Doctor reports
transport kind and path while retaining legacy pipe_* fields for existing
consumers. A Linux/WSL process requires a socket in that environment; it does
not discover a Windows pipe across the OS boundary automatically.
Chrome and Edge share the same Chromium automation backend, but they are
not interchangeable instances. Two Edge profiles can also have the same
name and family while exposing different tabs, cookies, extensions, and
signed-in state.
The installed browser and chrome Codex plugin packages also share the same
Browser client/service implementation; their manifests are product wrappers.
browserFamily chooses the extension/profile backend, not a separate engine.
The bridge therefore treats metadata.extensionInstanceId from getInfo as
the stable browser_id. A pipe name is transport metadata, not browser
identity. Extensions that do not report an instance ID are excluded from
discovery; use --pipe only as an explicit legacy transport override.
Use:
codex_list_browsers to inspect every live instance.codex_bind_browser with an exact browser_id when more than one instance
is live.The initial connection is fail-closed: if exactly one live instance exists it
is selected automatically; if several exist, browser tools return an ambiguity
error until the session is bound. Reconnects stay pinned to the selected
extensionInstanceId; they never rotate silently to another browser/profile.
For process-level pinning, use --browser-family plus
--browser-instance, CODEX_BRIDGE_BROWSER_FAMILY plus
CODEX_BRIDGE_BROWSER_INSTANCE, or the matching TOML keys. A family selector is
accepted only when that family has one live instance. --pipe remains an
explicit low-level transport override and cannot be combined with a browser
selector.
Rebinding while the current session owns tabs requires codex_finalize first,
or explicit end_previous_turn: true on codex_bind_browser. This performs the
official previous-turn cleanup before switching; it does not silently abandon
the old session. Finalization preserves handoff/deliverable marks.
The one-command install above adds the skill and MCP server configuration
together; no manual MCP JSON is needed. Claude Code 2.1.292 or later can add the
marketplace and install the plugin in one step. For a local checkout, use
claude --plugin-dir ..
The first MCP start can take a few seconds while npx fills its cache. After
that, the plugin reuses the cached package, or the globally installed command
when one is already on PATH.
The plugin defaults to the full 66-tool surface because Claude Code enables MCP
tool search by default: only server instructions and tool names enter the
initial context, and schemas are loaded on demand. codex_doctor is the only
schema marked alwaysLoad. The companion skill then loads one reference file
for the task instead of reading the entire tool manual.
For clients without tool search, or if you prefer manual MCP wiring, install the npm package globally and add:
{
"mcpServers": {
"codex-browser": {
"command": "codex-browser-bridge",
"args": ["--mode", "mcp"],
"transport": "stdio",
"env": {
"CODEX_BRIDGE_PROFILE": "basic"
}
}
}
}
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.
If your MCP client is launched from a GUI or a scheduler, prefer the absolute
command path printed by npm postinstall. If you need to recover it later,
run the out-of-band CLI doctor from npm's global install path:
$bridge = Join-Path (npm prefix -g) "codex-browser-bridge.cmd"
& $bridge --mode doctor
Paste install.suggested_mcp_config.mcpServers.codex-browser.command into the
client config. The suggested config starts with the 46-tool basic profile;
switch to network or full only when needed. File upload requires
CODEX_BRIDGE_UPLOAD_BASE; use the templates in examples/ for a
full config.
Codex and ChatGPT desktop already control the ChatGPT browser extension directly. Do not install this bridge as a Codex plugin: it would add a duplicate MCP path to the same browser. The bridge exists for Claude Code and other non-Codex MCP clients that need to reuse that existing browser session.
For Cursor, OpenClaw, Hermes Agent — see examples/. The npm
package also ships these examples under examples/.
The plugin already installs the skill. Clients without plugin support can copy the npm-package skill instead:
# Git Bash / WSL: global install → Claude Code skills
cp -r "$(npm root -g)/@delicious233/codex-browser-bridge/skills/codex-browser" ~/.claude/skills/
# Git Bash / WSL: or into a local project
cp -r node_modules/@delicious233/codex-browser-bridge/skills/codex-browser .claude/skills/
# PowerShell: global install -> Claude Code skills
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item -Recurse -Force "$env:APPDATA\npm\node_modules\@delicious233\codex-browser-bridge\skills\codex-browser" "$env:USERPROFILE\.claude\skills\"
# PowerShell: or into a local project
New-Item -ItemType Directory -Force ".claude\skills" | Out-Null
Copy-Item -Recurse -Force "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, and
multi-client MCP config templates are under examples/.
Configuration precedence is:
The default config file is .codex-browser-bridge.toml in the current working directory. Set CODEX_BRIDGE_CONFIG to use an explicit path; when it is set, the bridge does not fall back to the working-directory config:
Only an absent default file is optional. Explicit unreadable/missing files,
malformed TOML, unknown keys, empty selectors, invalid tool profiles and response
limits outside 1024..=8388608 bytes fail before browser work. Family and instance
form one selector group: the highest-priority source specifying either replaces
the whole lower-priority group. --mode doctor reports the effective selector
and source. basic/network/full select tools, not browser user profiles.
profile = "basic" # recommended; basic | network | full
browser_family = "edge" # chrome | edge | brave | opera | vivaldi
browser_instance = "..." # extensionInstanceId; required if >1 match
upload_base = "C:/Users/me/Downloads"
max_text_bytes = 1048576
max_image_bytes = 3145728
The same settings can be provided in MCP client config:
{
"mcpServers": {
"codex-browser": {
"command": "codex-browser-bridge",
"args": ["--mode", "mcp", "--profile", "network"],
"transport": "stdio",
"env": {
"CODEX_BRIDGE_BROWSER_FAMILY": "edge",
"CODEX_BRIDGE_BROWSER_INSTANCE": "extension-instance-id",
"CODEX_BRIDGE_UPLOAD_BASE": "C:\\Users\\me\\Downloads",
"CODEX_BRIDGE_MAX_TEXT_BYTES": "1048576",
"CODEX_BRIDGE_MAX_IMAGE_BYTES": "3145728"
}
}
}
}
CODEX_BRIDGE_UPLOAD_BASE enables codex_file_input and limits uploads to a specific directory. File upload is disabled until this is set explicitly; MCP clients do not always launch servers from a predictable working directory.
Large MCP responses are bounded so agents do not receive multi-megabyte DOM, JavaScript, CDP, or screenshot payloads by accident:
CODEX_BRIDGE_MAX_TEXT_BYTES caps each text content item. Default: 1048576.CODEX_BRIDGE_MAX_IMAGE_BYTES caps each base64 image content item. Default: 3145728..codex-browser-bridge.toml as
max_text_bytes and max_image_bytes, or via CLI flags
--max-text-bytes and --max-image-bytes.CODEX_BRIDGE_SOCKET_DIR overrides Unix socket discovery. Without it,
$XDG_RUNTIME_DIR/codex-browser-use is tried before /tmp/codex-browser-use.CODEX_BRIDGE_NO_AUTO_FOREGROUND=1 disables the automatic hidden-tab
activation before synthesized input. The default is to activate the tab;
disabling it can restore the old silent-input risk.codex://tabs is available as an MCP resource for clients that support resources. It returns tabs owned by the current bridge session, not every Chrome tab. The prompt templates login and extract-table are also exposed for clients that support MCP prompts.
[Browser][Tabs]codex_observe starts bounded tab/document observation before an action and
returns frames, dialog IDs, event/log cursors and explicit gaps. Navigation
composites arm before acting. codex_file_chooser captures chooser IDs/multiple;
uploads require configured CODEX_BRIDGE_UPLOAD_BASE and explicit
colocated_browser=true. Remote browser-host uploads and completed-download paths
are unsupported. File exports report path_scope=bridge_host, not browser
downloads. See parity contracts.
[Navigation][DOM][Page][Input]CUA pointer moves use a bounded no-ack window because current extension builds
apply but do not acknowledge mouseMoved; drag latency therefore follows the
number of supplied path points.
[Network][CDP][Session]Additional current-source tools are codex_clipboard (session virtual
clipboard), codex_webmcp (experimental top-document registration list/invoke),
and codex_content_export (bounded local GSuite/YouTube export).
# 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 # 46 tools
codex-browser-bridge --mode mcp --profile network # 65 tools
codex-browser-bridge --mode mcp --profile full # all 66 (default)
# Bound large MCP outputs
codex-browser-bridge --mode mcp --max-text-bytes 1048576 --max-image-bytes 3145728
The source also provides shell-friendly commands through the same schemas,
profiles, handlers, and safety checks. tools lists names without connecting;
tools NAME returns one schema.
codex-browser-bridge tools codex_locator
codex-browser-bridge call codex_list_browsers '{}'
codex-browser-bridge --max-output-bytes 4096 batch <<'JSONL'
{"name":"codex_user_tabs","arguments":{}}
JSONL
A call is one process and one browser turn. It ends that turn on exit, even
after a failure, so an unmarked tab can never be left owned by a process that no
longer exists; deliverable and handoff marks survive. batch reads one
{name, arguments} object per stdin line, keeps one turn, and stops on the
first error. Use --session-file <path> when several separate commands must
share one turn, or --keep-turn to deliberately leave the turn open.
--session-file is valid only with call/batch; MCP stdio and the interactive
CLI reject it. The v2 file binds the turn to an exact extension instance and is
locked for each invocation; concurrent use fails promptly. Its parent must exist.
Legacy/corrupt files fail rather than create a new session. Preserve such files
and recover/finalize the original turn before starting a new continuation.
The empty .lock sidecar is retained to prevent inode races; process exit releases
the OS lock. Same-profile cookies/storage are still shared. Ctrl-C and SIGTERM attempt cleanup only when the command is configured to finalize;
--keep-turn and an unfinalized --session-file intentionally leave the turn
open. CLI JSON results default to 16384 bytes
each and summarize images without base64; this byte limit is separate from MCP
content limits. The CLI is an optional entrypoint, not a separate capability
implementation.
MCP Client (Claude Code / Cursor / OpenClaw)
│ stdio JSON-RPC
▼
codex-browser-bridge (Rust binary)
│ length-prefixed JSON-RPC frames
▼
Local transport (Windows named pipe / Linux Unix socket)
│
▼
ChatGPT desktop app → ChatGPT browser extension → Chromium browser tabs
The bridge is a dual-era MCP server:
All 66 tools carry behavior annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) for client approval UX. See CHANGELOG.md for details.
This project is intentionally a thin compatibility adapter, not a second browser runtime. Upstream desktop-app and extension upgrades do not require a bridge release by themselves. After an upstream upgrade, run this smoke sequence:
codex-browser-bridge --mode doctorcodex_list_browserscodex_bind_browser when more than one instance is livecodex_get_infoRelease a patch only when the pipe contract changes, compatibility needs documenting, or a real regression is fixed. Do not add Playwright or another browser extension as a fallback layer.
This tool gives an agent access to your active browser session.
codex_file_input enforces path traversal prevention (canonicalize + prefix check, 10 MB limit)http:// and https:// URLsgit 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, lifecycle, types, schema, handlers, profiles)
browser.rs CDP + browser operations
client.rs Local transport + sticky attach
security.rs URL + file path validation
doctor.rs Local transport diagnostics
cli.rs Shell commands and interactive debug REPL
discovery.rs Local transport auto-discovery
protocol.rs Length-prefixed JSON-RPC frames
See ROADMAP.md. Highlights:
scripts/live-e2e.ps1)The official capability matrix and drift baseline live in docs/official-parity.md and docs/official-surface-baseline.json.
MIT. Maintained independently from OpenAI, Anthropic, and Google.
Thanks to LINUX DO for community support and feedback.
Expose the ChatGPT desktop app's browser bridge (formerly Codex Desktop) as an MCP server — drive Chrome and Edge from Claude Code and other agents.
Araçlar
Henüz araç listesi yok. Uzak sunucular ilk sağlık kontrolünden sonra bir liste alır.
SSS
Bu sayfadan Cursor, Claude Desktop, Claude Code veya VS Code için stdio yapılandırmasını kopyalayın. PlugMCP proxy'sini değil, yayıncının kurulumunu kullanır.
Bu kayıtta gerekli bir ortam değişkeni listelenmiyor.
Codex Browser Bridge yerel olarak stdio üzerinden çalışır.
Son kontrol: 2026-10-27. Expose the ChatGPT desktop app's browser bridge (formerly Codex Desktop) as an MCP server — drive Chrome and Edge from Claude Code and other agents.
