Codex Browser Bridge MCP server
Commit Nov 7, 2026Allows an AI client to control Chromium or Firefox browsers to inspect pages, fill forms, manage tabs, and execute multi-step automation tasks.
Also known as dariumi/codex-browser-bridge
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 7, 2026
- License
- MIT
What is Codex Browser Bridge MCP?
Codex Browser Bridge allows an AI client to control Chromium or Firefox browsers to inspect pages, fill forms, manage tabs, and execute multi-step automation tasks.
Summary generated from the project's README
About Codex Browser Bridge MCP server
Automating web interactions through your existing browser profiles is what codex-browser-bridge enables for developers using Codex. By connecting an AI client to your everyday Chromium or Firefox sessions, you can perform complex tasks like filling out forms, dragging elements, and managing tabs without needing to manage remote-debugging ports. This setup allows the AI to work within your signed-in sessions, ensuring that your existing accounts and cookies remain active and accessible.
The system operates via a local bridge that communicates with a browser extension using an authenticated WebSocket. Users can install the server through npm or Python distributions, which then require a manual step to load the unpacked extension into the browser. The server provides 38 specialized tools, including browser_view, browser_scripts, and browser_task, to facilitate deep page inspection and multi-step automation. It also supports advanced features like media capture, synthetic device streams, and saved action sequences through an Automation Studio.
What you can do with it
- 1Automate multi-step web workflowsAn AI client can execute a sequence of actions like navigating sites, filling forms, and verifying the final result.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledariumi/codex-browser-bridge is public and reachablegithub.com/dariumi/codex-browser-bridge ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/dariumi/codex-browser-bridge ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCodex Browser Bridge
Your browser. Your tabs. Your Codex.
An MCP server and browser extension for working in your everyday Chromium or Firefox profile.
Quick start · Studio · Installation · Agent guide · Русский
Connect Codex to the tabs you already use: inspect pages, fill forms, drag elements, work through multi-step tasks and verify the result. Signed-in browser sessions stay in the browser. No remote-debugging port is required for your personal profile.
Package availability: npm and Python distributions are prepared in this checkout. Registry publication and ownership of the package names have not been verified. Use the built
.tgz/.whlfiles until the first registry release; do not assume the registry commands already work.
Quick start
Choose one installer. Both use the same Node.js bridge and browser extension.
| Route | Requirements | Best for |
|---|---|---|
| npm | Node.js ≥22, npm | Installing the CLI directly |
| Python | Python ≥3.10, Node.js ≥22, npm | pipx / Python-managed environments |
| Git | Node.js ≥22, npm, Git; Python 3 for archive builds | Development and validated source updates |
Codex CLI must be installed and signed in to use browser chat. Loading the unpacked browser extension is a separate browser action.
npm
Install a downloaded/built package without cloning the repository:
npm install --global ./codex-browser-bridge-0.8.1.tgz
codex-browser-bridge setup
codex-browser-bridge doctor
After the package is published to npm, the first line becomes:
npm install --global codex-browser-bridge
setup creates a private connection file, registers the MCP server with Codex and exports both browser add-ons to writable, stable directories. It prints the paths, never the connection key. --no-codex skips registration; --no-start prepares files without starting the daemon.
Python
Install the wheel with pipx (recommended), or pip inside a virtual environment:
pipx install ./codex_browser_bridge-0.8.1-py3-none-any.whl
codex-browser-bridge setup
codex-browser-bridge doctor
After publication to PyPI: pipx install codex-browser-bridge.
The Python launcher includes the exact JS runtime archive and checks its SHA-256. The first setup installs its locked npm runtime dependencies into a versioned user cache. bootstrap performs only this dependency installation. Node.js and npm are required; Git is not. No install-time script changes your browser or Codex configuration automatically.
Connect the browser
- Chromium / Brave / Edge: open the browser's extensions page, enable developer mode and choose Load unpacked with the printed Chromium directory.
- Firefox: open
about:debugging→ This Firefox → Load Temporary Add-on and select the printed Firefoxmanifest.json. Temporary add-ons must be reloaded after a browser restart; permanent distribution requires Mozilla signing. - Open the extension settings and import the printed
connection.jsonfile. Keep it private. - Restart/reload Codex MCP, run
codex-browser-bridge doctor, then open a normal HTTP(S) page and its Codex chat.
Full connection guide · Agent setup · Package details
git clone https://github.com/dariumi/codex-browser-bridge.git
cd codex-browser-bridge
npm ci
npm run setup
npm run package
npm run doctor
Chromium loads extension/; Firefox loads dist/firefox/manifest.json. Source installations retain the existing .local/connection.json. See the installation guide before enabling delegated browser actions or self-development mode.
What it does
| Capability | Included |
|---|---|
| Browser actions | Screenshots, snapshots, forms, keyboard, pointer and HTML dragging, scrolling and navigation |
| Chat & handoff | Page-launched chat, model/reasoning selection, progress, plans and verified task results |
| Automation Studio | Saved JSON action sequences, import/export, stop and permission-aware resume |
| View profiles | Chromium viewport/mobile/touch/theme/timezone/locale/UA; Firefox document CSS zoom and scoped UA |
| Other extensions | Exact user-configured messages to cooperating extensions with an external API |
| Media | Playback metadata, captions, animations, actual video frames and bounded audio capture where supported |
| Virtual sources | Page-scoped test microphone, camera and synthetic screen streams; optional Linux native helper |
| Site control | Ask/deny domain rules, separate advanced consent and visible permission decisions |
| Workspace | Codex tab groups, preserved original tabs and cleanup of recorded temporary tabs |
| Long tasks | Opt-in scheduled sleep/wake in managed tasks, with real progress checked after waking |
| Floating launcher | Compact, draggable, keyboard-movable and hideable; restore it from popup or Studio |
| Privacy | Session-only chat/script storage by default; explicit persistence controls and history deletion |
38 MCP tools, including browser_view, browser_scripts, browser_extensions, browser_media, browser_devices, browser_task and browser_policy.
How it connects
flowchart LR
C[Codex] -->|MCP stdio| M[Bridge server]
M <-->|Authenticated WebSocket| E[Browser extension]
E -->|Site rules and approvals| T[Your browser tabs]
The local HTTP bridge listens on loopback. Remote agents can connect to a user's browser through SSH forwarding or the optional TLS gateway. Remote setup.
Chromium and Firefox
| Feature | Chromium | Firefox |
|---|---|---|
| Main page / open Shadow DOM | Yes | Yes |
| Input | Trusted CDP events | Synthetic DOM events; some sites reject them |
| Screenshots | Viewport and full page | Viewport |
| View profiles | Native CDP emulation, per-tab zoom | Document CSS zoom; limited User-Agent override |
| Raw CDP, native upload/dialog, console/network capture | Available | Unavailable |
| Cross-frame input | Advanced CDP route | Higher-level frame targeting unavailable |
User-Agent changes do not replace the entire device fingerprint. Autoplay, CORS, DRM, browser-internal pages and protected extension stores can limit actions. Report unsupported operations honestly. Studio boundaries · Diagnostics / Complex Lab.
Configuration and upgrades
Package installs keep connection keys, task state and exported extensions outside node_modules / site-packages. On Linux the default state directory is ~/.local/state/codex-browser-bridge; macOS and Windows use their user application-data directories. Override with BROWSER_BRIDGE_HOME or the exact BROWSER_BRIDGE_CONFIG path. A Git checkout continues using .local/ unless overridden.
codex-browser-bridge extension # Export or update both add-ons
codex-browser-bridge extension --browser firefox # Export Firefox only
codex-browser-bridge doctor --json # Diagnose without printing secrets
Exports detect local edits and refuse to overwrite them. --force explicitly replaces an existing bridge export. Keep export paths stable so the browser can retain its extension settings.
- npm/Python installations: upgrade with the package manager, rerun
setup, runcodex-browser-bridge restart, restart MCP and reload the exported add-on. Git-based self-updates and source editing are disabled in package installations. - Git installations: official-source update checks, scoped user policy, detached-worktree validation and rollback remain available. Dirty checkouts are preserved. Self-development requires a source checkout.
Complete package and publishing guide
Security and responsibility
The agent can act through signed-in accounts. Review the tasks you delegate. Built-in sensitive-site rules are a starting point: add your own protected domains. Only the user can approve access; scripts and integrations do not grant permission or weaken site restrictions.
Never share connection.json, tokens, private task history or your stored script library. Package allowlists exclude local configuration, logs and browser artifacts. Messages from pages and other extensions remain untrusted.
Provided under the MIT License, without warranties. To the extent permitted by law, authors and contributors accept no liability for agent actions or consequences. Read the Disclaimer.
Build and contribute
npm ci
npm run check
npm test
npm run package
npm run lint:firefox
npm run test:isolated
npm run test:firefox
npm run pack:npm
npm run pack:python
npm run test:python
Python wheel builds require Python, setuptools ≥77 and wheel (or use python -m build, which creates an isolated build environment). Package builds do not publish anything. Current verification scope and environment limitations are recorded in TESTING.md.
Installation · Studio · Devices · Remote · Diagnostics · Release notes
Codex Browser Bridge MCP questions
What browsers are supported?
The bridge works with Chromium-based browsers (including Brave and Edge) and Firefox.
Does it require a remote-debugging port for my personal profile?
No, signed-in browser sessions stay within the browser without needing a remote-debugging port.
How do I install it using npm?
You can install the package globally using npm install, then run the setup and doctor commands.