Connects AI agents to specific Chrome tabs to enable debugging, UI interaction, and automated testing within a developer workflow.
Also known as jobshimo/browser-link, @jobshimo/browser-link
- Stars
- 1
- Tools
- 4
- Downloads, 30 days
- 6,505
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is browser-link MCP?
browser-link connects AI agents to specific Chrome tabs to enable debugging, UI interaction, and automated testing within a developer workflow. It exposes 4 tools, such as all, readonly, no-eval.
Summary generated from the project's README
About browser-link MCP server
Connecting AI agents to specific Chrome tabs for debugging and UI testing is what browser-link enables. This developer-focused tool creates a bridge between MCP clients like Claude Code, OpenCode, or GitHub Copilot CLI and the browser tabs you explicitly authorize using a companion Chrome extension. Instead of giving an agent access to your entire browser, you select individual tabs to enable, allowing the agent to interact with the active session, including logged-in states and cookies.
The server provides 37 specialized tools, including browser.flow for multi-step sequences, browser.snapshot for DOM reading, and browser.click or browser.type for interaction. It also includes tools for managing permissions, handling network requests, and running arbitrary JavaScript. Because the agent acts within your existing browser session, it can navigate pages, respond to native dialogs, and manage downloads just as a user would. This setup is designed for a tight development loop where an agent reproduces a reported bug in a real UI, fixes the code, and then re-verifies the fix in that same tab.
What you can do with it
- 1Reproduce and fix UI bugsAn agent can use the browser to find a broken button and verify a code fix in the actual running application.
- 2Automate multi-step UI flowsDevelopers can instruct an agent to execute complex sequences of clicks and typing through a single command.
- 3Validate application behavior with JavaScriptAn AI client can execute custom scripts directly within a connected tab to inspect or manipulate the page state.
- 4Test browser permission handlingThe agent can programmatically grant or deny access to hardware like the camera or microphone for a specific origin.
Written from the project's README. Every use case is checked against a quote from it.
How to install browser-link MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall browser-link MCP in Claude Code
$ claude mcp add browser-link -- npx -y @jobshimo/browser-linkInstall browser-link MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"browser-link": {
"command": "npx",
"args": [
"-y",
"@jobshimo/browser-link"
]
}
}
}Install browser-link MCP in VS Code
.vscode/mcp.json
{
"servers": {
"browser-link": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@jobshimo/browser-link"
]
}
}
}Install browser-link MCP in VS Code CLI
$ code --add-mcp '{"name":"browser-link","type":"stdio","command":"npx","args":["-y","@jobshimo/browser-link"]}'Install browser-link MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"browser-link": {
"command": "npx",
"args": [
"-y",
"@jobshimo/browser-link"
]
}
}
}Install browser-link MCP in Codex
$ codex mcp add browser-link -- npx -y @jobshimo/browser-linkInstall browser-link MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.browser-link] command = "npx" args = ["-y", "@jobshimo/browser-link"]
Install browser-link MCP in Gemini CLI
$ gemini mcp add -s user browser-link npx -- -y @jobshimo/browser-linkInstall browser-link MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"browser-link": {
"command": "npx",
"args": [
"-y",
"@jobshimo/browser-link"
]
}
}
}browser-link MCP tools 4
Detected from the READMEallreadonlyno-evalno-map
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablejobshimo/browser-link is public and reachablegithub.com/jobshimo/browser-link ↗Pass
- Package names this repository as its source@jobshimo/browser-link names jobshimo/browser-link as sourcenpmjs.com/package/@jobshimo/browser-link ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @jobshimo/browser-linknpmjs.com/package/@jobshimo/browser-link/v/1.0.1#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/jobshimo/browser-link ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @jobshimo/browser-linkPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub🔗 browser-link
Developer-focused bridge between your MCP client (Claude Code, OpenCode, GitHub Copilot CLI, …) and the Chrome tabs you explicitly enable.
Built for developers debugging real UIs from the agent's seat — reproducing bugs, validating fixes, teaching the agent how an app actually behaves. Not a consumer browser-automation product.
⚠️ Read this before installing
Important notice
browser-link is a development tool. It connects an AI agent to the Chrome tabs you choose, and in those tabs the agent acts with your own session: it sees and can use everything the browser holds in them, including active logins, cookies and tokens, autofilled passwords and payment cards, email, documents and any data the page shows or lets you submit. It can click, type, submit forms and download files as you would.
Connect only tabs an agent should operate, disconnect them when you are done, and do not use it on sites whose terms forbid it or with data you cannot afford to expose. Deciding what to grant access to, and what the agent does with that access, is solely the user's responsibility.
The software is provided "as is", without warranty of any kind, under the MIT license. The authors accept no liability for losses, damage or misuse arising from its use.
browser-linkopens a bridge between your MCP client and the Chrome tabs you explicitly enable through a companion extension. On every tab where you press "Connect this tab" in the extension popup, the agent can read its DOM, click, type, press keys (trusted keyboard input), drag, run a multi-stepbrowser.flowsequence, run arbitrary JavaScript, navigate, answer native dialogs (alert/confirm/prompt), follow popups opened by the page (window.open/target=_blank), and pre-grant or pre-deny browser permissions (geolocation, notifications, camera, microphone, clipboard, sensors) for the tab's origin — including any logged-in session, saved card, wallet, banking page or admin panel that tab is currently showing.This is a developer tool, not a consumer-grade browser-automation product. Treat the agent like a junior dev with remote control of those tabs. Only enable tabs where you would let an automated process act on your behalf, and disconnect them when you are done. You are responsible for every action the agent performs on the tabs you explicitly enable.
Contents
- What it is
- Quick start
- Upgrading to 1.0
- How it works
- Use cases
- What the agent can do
- Persistent UI map
- Activity trail
- Customising
- cdp-direct mode (no extension)
- Stability
- Security model
- Where your data lives
- For contributors
- Author
- License
What it is
A development-oriented MCP server that lets your editor's agent see and act on a Chrome tab you explicitly enable — without giving it your whole browser. Designed for the loop "user reports bug → agent reproduces it in the real UI → agent fixes the code → agent re-verifies in the same tab", not for unattended consumer automation.
- ✅ What it does — exposes 37 MCP tools: 31
browser.*bridge tools (list_tabs, ping, snapshot, find, state, canvas_screenshot, screenshot, click, type, press, drag, flow, navigate, evaluate, wait_for, wait_for_tab, dialog_respond, set_permission, download, console, network, network_body, claim/release/my_tabs, events, activity, reset, andmanual, which needs no tab) and 6 persistent-map tools, so the agent learns your apps across sessions. - ✅ What it needs — Node ≥ 22.22.2 and Chrome / Chromium / Edge / Brave / Vivaldi on Chromium ≥ 118 (from 118 an active debugger session keeps the extension's service worker alive; the manifest declares it). No accounts, no telemetry. The only request the server makes by itself is the npm registry update check described under Where your data lives.
- 🚫 What it does NOT do — touch tabs you have not pressed Connect on,
persist domain data in the map (selectors and flows only, structure never
content). Beyond the update check, the only network traffic it causes is
what you ask for:
browser.downloadfetches the URLs the agent requests. - 🔒 How it stays private — WebSocket bridge is loopback-only
(
127.0.0.1:17529) and kernel-attested per connection. - 🛑 How you stop it — the extension popup lists every running
browser.flowwith a one-click Stop, across every connected tab. See the Flows panel.
Quick start
npm install -g @jobshimo/browser-link
browser-link
The second command opens a full-screen interactive UI (English / Spanish) built on Ink. It walks you through the four-step setup:
- Register
browser-linkwith your MCP client. Pick Claude Code (writes~/.claude.json/%USERPROFILE%\.claude.json), OpenCode (writes~/.config/opencode/opencode.jsonon every OS), or GitHub Copilot CLI (writes~/.copilot/mcp-config.json, override viaCOPILOT_HOME). Restart the client afterwards. - Drop the trigger block into the agent's global
.md. Optional but recommended — see Agent instructions below. Without it the agent has no reason to callbrowser.snapshotwhen you say "the button is broken"; it will read code and guess. - Install the Chrome extension. The UI prints the absolute path to the
bundled assets and the OS-specific steps (
chrome://extensions→ Developer mode → Load unpacked). The extension carries a fixed public key, so its id is the same on every install, and the server accepts only that id (see Upgrading to 1.0). After updating the server, reload the extension inchrome://extensions. - Connect a tab. Click the browser-link icon in your Chrome toolbar and press Connect this tab on the tab you want the agent to see. The extension speaks English and Spanish (see Extension language).
After the first run, browser-link opens on a status view: the running
server (version, PID, uptime, ports, outdated or not), multi-agent, the
instructions block per client, cdp-direct, updates and the activity trail,
with every menu entry and its usual hotkey right below it. Tab opens the
full menu; every other screen still returns to the menu, as before. When no
server is running the status rows say so: the console reads the running
primary's GET /version, it never starts one.
The Flows panel
The same popup is where you watch — and stop — what the agent is doing.
While any browser.flow is running, a Flows section appears:
- Running flows — one row per in-flight flow, across every
connected tab (a runaway flow is rarely on the tab you happen to be
looking at): the tab's title, how long it has been going, where it is
(
step 3/7, orstep 2/5 · iteration 12/50inside arepeat), and a Stop button. One click, no confirmation. The row readsStopping…for the moment it takes the runner to reach its next step check. A detached flow is labelleddetached ·and gets an amber dot instead of a green one: it is the one row that will keep going with no agent attached, so it is the one row that most needs the button next to it. - Recent flows — the last 20 finished flows of the tab you are
looking at: outcome (
completed/cancelled/failed/expired), how long it took, how many steps or iterations it got through, and which step failed when one did. A detached run that hit its 30-minute ceiling readsexpired; one that Chrome killed the service worker under readsfailed · extension worker was terminated — not resumed.
Both are hidden entirely when there is nothing running and nothing remembered, so an idle popup looks exactly as it did before.
History lives in chrome.storage.session and dies with the browser
session by design — this is an operator view, not an audit log. Entries
store UI structure and outcomes only: counts, durations, a step index and
a step kind. Never page text, never a selector, never anything you typed.
Failure messages in particular are dropped rather than trimmed, because a
real find failure quotes the page back at you.
╭─ browser-link — setup ────────────────────────────────────────────╮
│ v0.19.1 │
│ │
│ Pick an action ⋅ or press the bracketed key│
│ │
│ SETUP │
│ ❯ [r] Register browser-link with an MCP client │
│ [i] Agent instructions — trigger block in global .md │
│ [p] Permissions — which browser.* tools to expose │
│ [m] Multi-agent — let multiple MCP clients share one bridge │
│ │
│ DIAGNOSE │
│ [d] Run doctor (diagnose current setup) │
│ [u] Check for updates on npm │
│ [f] Free port — stop a stuck browser-link holding 17529 │
│ │
│ REFERENCE │
│ [e] Show Chrome extension install steps │
│ [L] Language — switch between English and Español │
│ [w] Show the welcome screen │
│ [a] About / Help — what is this and how it works │
│ [g] Open the GitHub repository │
│ [q] Quit │
│ │
│ ↑↓ navigate · ↵ select · a-z hotkey · l language · q quit │
╰─────────────────────────────────────────────────────────────────────╯
Every action above is also a subcommand you can script:
browser-link install # register in every detected client
browser-link install --client claude # register only in Claude Code
browser-link uninstall --client opencode # remove from one client
browser-link instructions # status of the trigger block per client
browser-link instructions install # insert/refresh the block in every detected client
browser-link instructions uninstall --client claude
browser-link extension # show extension assets path + steps
browser-link doctor # diagnose current setup (running vs installed version, live processes); every probe runs in parallel
browser-link tools # show which MCP tools are enabled
browser-link tools disable browser.evaluate
browser-link tools preset readonly # all | readonly | no-eval | no-map
browser-link config get # list every known setting
browser-link config set idle-ttl 15 # idle-disconnect TTL, in minutes ("never" disables it)
browser-link config set flow-recording on # opt in to recording flows by demonstration (off by default)
browser-link config set cdp-direct.enabled true # opt in to cdp-direct mode (off by default, see below)
browser-link config set map-learning off # stop the map learning from use (on by default, see below)
browser-link cdp allow # grant time-boxed cdp-direct access (only you can run this)
browser-link cdp status # enabled?, port, grant remaining, endpoint reachable?
browser-link cdp revoke # revoke the current cdp-direct grant
browser-link map # list apps the persistent UI map knows about
browser-link map show <app> # entries + flows for one app (app_key or origin)
browser-link map forget <app> --yes # delete a whole app and its data
browser-link map forget <app> --flow <name> # delete just one named flow
browser-link map export --out map.json # export the map (or one app) as JSON
browser-link map import map.json # import an export (merge by default, --replace to overwrite)
browser-link multi-agent disable # opt out of the default shared-bridge mode
browser-link multi-agent auto-reelect enable
browser-link stop # stop every live browser-link server (17529 owner included), one line each
browser-link updates # check the npm registry for a newer version
browser-link about # the full help page
browser-link help # list every subcommand
browser-link version prints the version and returns at once: it does not
load the config, so a corrupt config never warns there.
doctor starts its slow checks together (both port probes, the running
server's /version, the Chrome debugger-flag scan and the live-process
scan), so a run lasts about as long as the slowest process scan instead of
their sum.
Windows: skip the npm shim for faster CLI calls
Each browser-link … call from PowerShell or cmd goes through npm's
browser-link.cmd / browser-link.ps1 shim, which starts its own shell
before Node: that shim costs 0.7–3.7 s per call on Windows, not
browser-link. Call the installed CLI directly instead. Find the global
node_modules folder with npm root -g and add a function to your
PowerShell profile (notepad $PROFILE):
# npm root -g printed e.g. C:\Users\you\AppData\Roaming\npm\node_modules
function browser-link { node "C:\Users\you\AppData\Roaming\npm\node_modules\@jobshimo\browser-link\dist\cli.js" @args }
In cmd, the same with a macro:
doskey browser-link=node "<npm root -g>\@jobshimo\browser-link\dist\cli.js" $*.
The function only changes your terminal: the MCP server your client starts
pays the shim once per session, not once per call.
Upgrading to 1.0
1.0.0 is the hardening release. Most of it is stricter checks on who may talk to the bridge, so a few things that worked before are now refused. If you come from 0.52 or older, do this once:
- Update the server:
npm install -g @jobshimo/browser-link@latest, then restart your MCP client. - Reload the extension in
chrome://extensions, from the extension folder of the version you just installed (the console's setup step prints its path), so the extension and the server are the same version. A 0.51 or older extension, or any extension without the pinned id, is refused, and its popup says so ("it does not accept this extension's id. Reload the extension from the installed browser-link version."). If the id changes, Chrome treats it as a new extension and its stored settings (idle timeout, flow recording, language) start fresh. - Run the browser as the same OS user as the server. A browser that runs as another user of the machine is refused (see below).
- If you used the Admin window to change tools, cdp-direct or MCP client registration, use the console instead (commands below).
Stored activity rows are not changed by the update.
What now stops a connection
Since 1.0.0 the bridge accepts a connection only if every check passes. The extension popup shows the reason when one fails, and the server log names the cause of every refusal:
| Check | Refused when | Popup says (short) |
|---|---|---|
| Origin | The Origin is missing, or is not exactly chrome-extension://celegobaahdoaigibmjmekhopegfkhpe or an id you allowed |
it does not accept this extension's id |
| Owner | The browser process runs as another OS user than the server, or its owner cannot be read | runs as another user / could not read which user |
| Name | The process is not a Chrome, Chromium, Edge, Brave or Vivaldi binary | not a supported Chromium-based browser |
| Path | Strict mode only (below): the executable path is not in your list, or cannot be read | the path is not in peerExecutablePaths |
Three more reasons can appear: the program that opened the connection could not
be seen, it could not be identified, or checking it failed. A connection with no
Origin (a script, for example) is refused before any process
lookup runs.
On Windows, netstat can omit a connection that was just opened from its first
snapshot, so the server looks again, up to six snapshots over about 1.25 s, before
refusing. If a refusal still happens, the popup says "The browser-link server
refused the connection: it could not identify the program that opened the
connection." (or, when the diagnosis itself cannot answer, "WebSocket connection
failed. Is the MCP server running?"), and the server log line says how many
snapshots were taken and how many rows mentioned the port.
Allowing another extension id (experts only). To connect your own build of
the extension, add its id to allowedExtensionIds in config.json, in the data
folder (see Where your data lives):
{ "allowedExtensionIds": ["abcdefghijklmnopabcdefghijklmnop"] }
An id is exactly 32 characters, each a letter from a to p. Any other entry
(a prefix, a wildcard, a full chrome-extension:// origin) is dropped with a
warning in the server log. The pinned id is always allowed. You edit this key by
hand: it cannot be set from the Admin window, the console, the bridge or an MCP
tool. browser-link doctor lists the ids in effect.
Strict mode by executable path (experts only). peerExecutablePaths in
config.json makes the server also require the browser's full path to be in a
list you wrote (see Security model). Before turning it on:
- A list with no valid absolute path refuses every browser. A mistyped list never turns the check off.
- A
config.jsonthe server cannot parse falls back to the defaults, with a warning in the log. That turns strict mode off, drops your allowed ids and clears the tool deny list. Keep the file valid.
Known gap. The peer check does not tell apart two programs that both run as
your user. A process that runs as you but is confined away from your files, while
it can still open a loopback connection (a Flatpak or Snap app with network
access, a macOS App Sandbox app with network.client, a Windows low-integrity
process), passes the same-user check, and it passes the name check if its binary
carries a browser's name. Strict mode closes that gap by path. Malware already
inside your browser is outside this model too (see
Security model).
On Windows the lookup also counts a socket that netstat lists only as bound
(foreign port 0) when no row to the server exists. If one process has a row to
the server and another has a bound-only row for the same endpoint, the row to the
server decides instead of the lookup refusing as ambiguous.
The Admin window no longer changes what an agent may do
Anything that can reach the bridge could have made these changes from the Admin window, so in 1.0.0 the window shows each one as a readout (the current value and the console command) and the server refuses the write. The console does all of them:
| What | Command |
|---|---|
| Disable or enable an MCP tool | browser-link tools disable <tool> / browser-link tools enable <tool> |
| cdp-direct on or off | browser-link config set cdp-direct.enabled true / browser-link config set cdp-direct.enabled false |
| cdp-direct grant lifetime | browser-link config set cdp-direct.grant-ttl <minutes> (a whole number of minutes, or never) |
| Register with an MCP client | browser-link install --client <claude|opencode|copilot>; to remove: browser-link uninstall --client <id> |
Still available from the Admin window: console language, multi-agent,
auto-reelect, the instructions auto-refresh, the activity trail switches,
doctor, the update check, and installing or removing the instructions block per
client. The cdp-direct port and the downloads folder were already readouts.
browser-link MCP questions
How do I add browser-link MCP to Claude Code?
Run claude mcp add browser-link -- npx -y @jobshimo/browser-link in your terminal. Add --scope user to make it available in every project.
How do I add browser-link MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does browser-link MCP provide?
It exposes 4 tools, including all, readonly, no-eval, no-map.
What can the agent do once a tab is connected?
The agent can read the DOM, click, type, drag, run multi-step flows, execute arbitrary JavaScript, navigate, and handle browser dialogs.
Is my data safe when using browser-link?
The server uses a loopback-only WebSocket bridge and does not touch tabs unless you explicitly connect them. It does not persist page content in its UI map.
Can I stop an automated process if it goes out of control?
Yes, the Chrome extension provides a Flows panel where you can see all running flows and stop them with a single click.
What browsers are supported?
It works with Chrome, Chromium, Edge, Brave, and Vivaldi on Chromium version 118 or higher.