Purpose
chromium-bridge is an MCP bridge tool that connects Chromium-based browsers with Claude Code. The official "Claude in Chrome" extension can connect in some Chromium browsers (such as Arc, Vivaldi, etc.), but automation hangs: its tools are based on the tab groups API, and that API is missing or broken in these browsers. This bridge uses only the ordinary chrome.tabs / chrome.scripting / chrome.debugger, so it works in any Chromium browser that can load extensions.
Main capabilities
- Browser automation tools: navigation, clicking, reading page text, screenshots, filling forms, running JavaScript, managing tabs, reading console and network information, closing tabs, uploading files, etc.
- Exposes browser_* tools to Claude Code via MCP.
- Provides an in-browser chat panel (equivalent to a replacement for the "Claude in Chrome" sidebar): click the extension icon to open it; the panel can view tabs, read pages, take screenshots, and click.
- The panel supports model selection (Default is read from ~/.claude/settings.json, others are hard overrides, switching takes effect immediately and is remembered), and also supports the environment variable CHROMIUM_BRIDGE_CHAT_MODEL startup override.
- Chat history: the 🕓 button in the panel header lists past conversations (stored in the panel localStorage, up to 30 entries).
- After each turn, a usage line is displayed: turn tokens (↑ input including cache / ↓ output) and cumulative session cost (estimated value in subscription mode).
- Screenshots are displayed in the chat stream (click to enlarge), and are not saved in history.
- Supports pasting images from the clipboard (Cmd+V in the input box, up to 5 per message), and only markers are kept in history.
- "Ask before acting" mode (checkbox above the input box): read operations (tabs, text, screenshots, console, network) are executed without asking; mutating operations (click/type/navigate/JS/form/close tab/file upload) wait for an Allow / Deny confirmation card. After seeing a denial, the agent continues the conversation. Switching takes effect immediately, with no need to rebuild the session.
- Page indication: when ClWhen aude operates on a tab, an orange halo and a “✳ Claude is working…” marker appear at the page edge, fading out 2.5 seconds after the last operation; a virtual cursor (orange arrow) slides toward the operation point, pulses a ring when clicking, and disappears after being stationary for 3.5 seconds. Both are hidden in screenshots to avoid interfering with the model's coordinate judgment; pages where scripts cannot be injected (such as chrome://) are silently skipped.
- UI language: The panel defaults to English and automatically switches to Russian when the browser UI language is Russian; the language selector in the bottom bar (Auto / English / Русский) can override automatic detection, and page markers follow the same selection.
Usage
Extension installation: Clone the repository, open chrome://extensions (make sure you are in the correct space/profile), enable “Developer mode”, click “Load unpacked”, and select the extension/ folder.
MCP server installation (two ways):
- Via npm: claude mcp add -s user chromium-bridge -- npx chromium-bridge
- From a clone: cd server && npm install, then claude mcp add -s user chromium-bridge -- node "$(pwd)/index.mjs"
It loads when a session starts — after installing the extension, restart your Claude Code session. Other MCP clients can add this to their configuration:
{ "mcpServers" : { "chromium-bridge" : { "command" : " npx " , "args" : [ " chromium-bridge " ] } } }
Check: the browser_status tool should return {"connected": true}.
Port: CHROMIUM_BRIDGE_PORT (default 8929, server-side only); the extension always connects to 8929, so changing the port also requires modifying WS_URL in extension/sw.js and extension/chat.js.
How it works: Apart from basic tab operations, everything is implemented through chrome.debugger (CDP) — screenshots do not require activating the tab,clicks are real mouse events, and console/network collection begins after the first CDP contact with that tab.
Use cases
In Chromium browsers where the official Claude in Chrome extension cannot automate properly (Arc, Vivaldi, etc.), use Claude Code or the built-in chat panel to drive the browser for web operations, information reading, and automation tasks.
Limitations
- Available only while the server is running (usually an active Claude Code session with chromium-bridge MCP); otherwise the panel shows “Server unavailable”.
- The extension exists in only one browser profile — it must be installed in the profile you want to automate.
- The popup loses focus (clicking the page) and closes; this is browser behavior. Session context is not lost: the panel remembers the session_id, and the server resumes the conversation via Agent SDK resume. An in-progress turn is interrupted when the popup closes.
- While the server is running, periodic pings keep the extension service worker awake; if the worker is still asleep (for example, just after the server starts), the keepalive alarm wakes it within about 30 seconds, and the server waits up to 12 seconds to reconnect before reporting an error.
- Trust model: The WS server listens on 127.0.0.1 and rejects connections whose Origin is not chrome-extension:// to block web pages; however, it does not distinguish between different extensions, and local non-browser processes can forge the Origin header — anything running as your user is trusted, the same as with most local development tools. Do not run this bridge on a shared machine.
- On the first CDP action, the browser shows the “Chromium Bridge started debugging this browser” bar; this is normal. Closing that bar disconnects the debugger (it will reattach on the next action).
- Console/network are not recorded retroactively — collection starts only after the first contact with the tab.
- Port 8929 is exclusive to one session: a second parallel Claude Code session cannot start its own WS server (the extension stays connected to the first one).
