# dashi96/chromium-bridge [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/dashi96/chromium-bridge  
**GitHub Stars:** 5  
**npm Downloads (last month):** 879  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/dashi96-chromium-bridge

## Description
MCP server + Chrome extension that connects Claude Code to Chromium-based browsers (Arc, Vivaldi, Brave) where the official Claude in Chrome extension doesn't work — navigate, click, read pages, run JS, and record GIFs in the user's real browser.

## Tools
Capabilities this server exposes over MCP:

- **browser_status** — Check whether the browser extension is connected to the bridge. Returns {connected: boolean}. Read-only, no side effects. Call it first in a session, or when other browser_* tools fail, to distinguish "extension not connected" from page-level errors.
- **browser_tabs_list** — List all open browser tabs with their id, title, and URL. Read-only. Use it to pick a tabId for the other browser_* tools; prefer reusing an existing tab over creating a new one when the target page is already open.
- **browser_tab_create** — Open a new browser tab and return its id and windowId. Mutating: adds a tab to the user's real browser and focuses it. Use when a fresh page is needed; to work with a page that is already open, find its id via browser_tabs_list instead.
- **browser_tab_close** — Close a browser tab by id. Destructive: the tab and its unsaved page state are gone, with no undo. Close only tabs this session created, unless the user explicitly asked to close theirs.
- **browser_navigate** — Navigate an existing tab to a URL, or move through its history with url="back" / url="forward". Mutating: replaces the page currently shown in that tab. Returns when navigation is committed; dynamic pages may still be rendering — verify with browser_page_text or a screenshot before interacting.
- **browser_page_text** — Get a tab's title, URL, and visible text (up to 80 kB) from the live DOM. Read-only and cheap — prefer it over a screenshot whenever layout does not matter. Content rendered to canvas or images is invisible to it; use a browser_computer screenshot for those.
- **browser_computer** — Mouse, keyboard, and screenshots in a browser tab via the DevTools protocol; the tab does not need to be active (first use shows Chrome's "started debugging" info bar — that is expected). Actions: screenshot (viewport image in CSS pixels — its coordinates map 1:1 to click coordinates), zoom (magnified region [x0,y0,x1,y1]), left_click, right_click, double_click, triple_click, hover, left_click_drag (start_coordinate→coordinate), type (insert text at the current focus), key (space-separated combos, e.g. "cmd+a Backspace"), scroll (scroll_direction+scroll_amount), scroll_to (ref), wait (duration, max 10 s). Clicks, typing, and key presses are real input events and mutate page state; screenshot/zoom/hover/wait are read-only. Positions come from coordinate:[x,y] or from a ref returned by browser_read_page/browser_find — refs are more reliable than eyeballed coordinates.
- **browser_read_page** — Accessibility tree of the page with a ref id per element; use refs with browser_computer (clicks, scroll_to) and browser_form_input. filter=interactive returns only clickable/editable elements — a compact map of the page. Read-only. Refs go stale after navigation or heavy DOM changes; call again to refresh.
- **browser_find** — Find elements by visible text, accessible name, or role, and return their refs for use with browser_computer and browser_form_input. Read-only. Cheaper than reading the whole accessibility tree when you know what you are looking for. An empty result means nothing matched — not an error.
- **browser_form_input** — Set a form control's value directly in the DOM: input/textarea/contenteditable (text), select (option value or label), checkbox/radio ("true"/"false"). Fires input/change events so frameworks pick the value up. Mutating. Target by CSS selector or ref. Reliable for plain form fields; rich editors (CodeMirror and the like) and custom comboboxes often ignore it — for those, click the field with browser_computer and type.
- **browser_click** — Click an element via DOM .click() by CSS selector. Mutating. Works without the debugger — including on pages where CDP attach fails — but only fires the click handler, with no hover/focus/mousedown chain. If the page ignores it (custom dropdowns, canvas UI), use browser_computer left_click for a real mouse event.
- **browser_upload_file** — Put local files into an <input type="file"> selected by CSS selector, as if the user picked them in the file dialog (fires change). Mutating. files are absolute paths on the user's machine; the input must already exist in the DOM.
- **browser_javascript** — Run arbitrary JavaScript in the page context and return the resolved value (await is supported; runs with the page's own permissions). Can read and mutate anything on the page — treat as mutating unless the code is clearly read-only. Never call alert/confirm/prompt: modal dialogs freeze all automation. Requires the CDP debugger.
- **browser_console_messages** — Read a tab's console output (log/warn/error), newest 200 entries. Read-only unless clear=true, which empties the buffer after reading. Messages are captured only from the first time a CDP tool touches the tab — nothing is recorded retroactively; reload the page after attaching to capture its startup logs. Use pattern (regex) to cut noise.
- **browser_network_requests** — List a tab's network requests (method, URL, status), newest 200. Read-only unless clear=true, which empties the buffer. Captured only from the first CDP touch of the tab — reload the page after attaching to see its full traffic. urlPattern (regex) filters by URL.
- **browser_resize_window** — Resize the browser window that contains the tab to width×height CSS pixels. Mutating and user-visible: it resizes the user's real window. Use for reproducing responsive layouts or framing a recording, and consider restoring the original size afterwards.
- **browser_gif_start** — Start recording the tab into an animated GIF: a frame every intervalMs (default 800 ms); on long recordings the frame rate halves automatically so the whole scenario fits in ~80 frames. One recording per tab at a time; starting twice is an error. Nothing is saved until browser_gif_stop.
- **browser_gif_stop** — Stop the recording started by browser_gif_start and write the animated GIF to an absolute path on the user's machine. Mutating: creates or overwrites that file. Errors if no recording is active or no frames were captured.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "chromium-bridge": {
    "command": "npx",
    "args": ["-y","chromium-bridge"]
  }
}
```

## Documentation

## What dashi96/chromium-bridge MCP server does

The dashi96/chromium-bridge MCP server gives an MCP client control of a Chromium-based browser profile through a browser extension. It can inspect open tabs, create or close tabs, navigate pages, read visible content, inspect accessibility information, interact with controls, execute JavaScript, upload local files, inspect console and network activity, resize the browser window, and record animated GIFs.

The bridge is intended for real browser sessions. Actions such as navigation, clicking, typing, form changes, JavaScript execution, file uploads, tab closure, and window resizing can change the user's browser or the state of a web page. Read-only operations include connection checks, tab listing, page text, accessibility inspection, element lookup, screenshots, hover, waiting, and inspection of captured console or network data.

## How it works

The project has two parts: an MV3 extension and a local MCP server. An MCP client starts the server over stdio. The server then communicates with the extension over a WebSocket bound to 127.0.0.1 on port 8929 by default. The extension uses Chrome APIs for tabs, scripting, and debugging, and sends results back to the MCP tools.

Start a session with `browser_status` to determine whether the extension is connected. Use `browser_tabs_list` to find a tab ID before calling page or interaction tools. Accessibility references from `browser_read_page` and `browser_find` can be passed to computer and form tools; these references can become invalid after navigation or major DOM changes.

The browser's debugging protocol is used for most advanced operations. The first CDP action displays a browser notification that debugging has started. Console and network collection begins only when the tab is first touched, so earlier events are not recovered retroactively.

## Setup and configuration

Install the extension by cloning the repository, opening `chrome://extensions` in the browser profile to automate, enabling Developer mode, and loading the `extension/` directory as an unpacked extension.

The MCP server can be started from npm with `npx chromium-bridge`, or directly from a clone with Node after running `npm install` in `server/`. A Claude Code registration uses the server name `chromium-bridge`; other MCP clients can use a stdio entry with `npx` and the package name. Restart the client session after adding the server and extension.

The server port can be changed with `CHROMIUM_BRIDGE_PORT`, but the extension's WebSocket URL must also be edited to use the same port. The optional `CHROMIUM_BRIDGE_CHAT_MODEL` variable selects the startup model for the extension chat panel. The chat panel otherwise uses the model configured through the Claude Code environment or its own model picker, and authenticates through the Claude Code login.

## Tools and capabilities

The dashi96/chromium-bridge MCP server exposes tools for:

- Checking extension connectivity and listing, opening, closing, or navigating tabs.
- Reading visible page text and accessibility trees, or finding elements by text, role, or accessible name.
- Performing mouse, keyboard, scrolling, zoom, screenshot, and wait actions through the browser debugger.
- Filling standard controls, clicking with DOM `.click()`, and uploading absolute local file paths.
- Running asynchronous JavaScript in the page context.
- Reading or clearing captured console messages and network requests with optional regular-expression filters.
- Resizing the containing browser window and recording a tab to an animated GIF.

## Limitations and notes

The extension is installed in one browser profile, so the selected profile determines which tabs the agent can access. The local server accepts extension-style origins but does not distinguish between different extensions; a local process running as the same user could imitate that origin. Do not run it on a shared machine.

Only one session can own port 8929 at a time. The extension service worker may need up to about 30 seconds to wake, while the server waits up to 12 seconds for reconnection in some startup cases. Closing the browser's debugging notification detaches the debugger and causes the next applicable action to attach again.

The chat popup closes when it loses focus, although its session context can be resumed. An in-progress turn is interrupted when the popup closes. GIF output is written to an absolute local path, and stopping a recording can overwrite the specified file.

_Full upstream README: https://allmcps.com/mcp/dashi96-chromium-bridge/readme_