EvannZhongg/BrowserAttach

English · 简体中文
Drive the Chrome / Edge tabs you already have open and already signed in from an MCP client. BrowserAttach connects to the browser through a locally paired extension, keeps your existing sign-in state, and needs neither a remote debugging port nor a separate automation browser.
npm · Usage guide · Architecture · Agent integration · Test report · Issues · Contributing
## What it does
Discover multiple browser profiles, pick one precisely, claim a tab exclusively, and release it when done.
Control existing ordinary file:// tabs after enabling BrowserAttach's Allow access to file URLs setting in the browser's extension details; use the same discovery, claim, observation and input tools.
Read the accessibility tree, query names/values/nearby field context, inspect field values and supported editor models; click, fill and type through refs or strict CSS/XPath, HTML label, placeholder and AX role/name locators. Type can also target the currently focused field explicitly.
Native pointer hover, stepped drags and conditional waits; select HTML options without opening a native popup.
Navigate and go back/forward, open or close tabs, handle JavaScript dialogs, upload local files, and capture the whole page or a single element.
Evaluate JavaScript expressions in the main page; read console, page-error, network and navigation logs captured after claiming, with bounded available stacks and request initiators; opt in to bounded, redacted request/response details when XHR/fetch needs verification.
Read one HTTP(S) URL in a temporary background tab with the profile's sign-in, returning rendered text, current DOM, or complete JSON with the main-document HTTP status when observed.
Standard stdio MCP with 24 tools. The Hub listens on loopback only and pairs with the extension through a random key.
## Requirements
Node.js 22 or newer, plus npm.
Chrome / Edge 125 or newer with permission to load unpacked extensions. Latest stable is recommended.
An MCP client that speaks stdio MCP and can find Node/npm on PATH.
## Quick start
### 1. Install and pair
sh
npm install --global @evanzhong/browser-attach
browser-attach setup
setup prints a stable extension directory and starts the local Hub. The directory is usually:
Windows: %USERPROFILE%\.browser-attach\extension
macOS / Linux: ~/.local/share/browser-attach/extension
Open chrome://extensions or edge://extensions, enable developer mode, choose "Load unpacked" and load that directory. Load it once for every browser profile you want to expose; the extension options page lets you set a recognizable profile name.
Or without a global install:
sh
npx --yes --package=@evanzhong/browser-attach@latest browser-attach setup
### 2. Configure the MCP client
Merge the following into your client's MCP configuration, or see mcp-config.json:
json
"mcpServers": {
"browserattach": {
"command": "npx",
"args": ["--yes", "--package=@evanzhong/browser-attach@latest", "browser-attach", "mcp"]
On Windows clients that require a full command extension, use npx.cmd. With a global install you can also configure "command": "browser-attach", "args": ["mcp"]. Restart the MCP client to discover the tools.