Chromium Bridge

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.