SkillAgentSearch skills...

browser-controller

MCP server + Chrome extension that gives AI agents control of your real browser with existing sessions and logins

Install / Use

claude mcp add compnew2006 -- npx -y github:compnew2006/browser-controller

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

72/100

Category

Automation

Supported Platforms

Claude Code
Claude Desktop

Our assessment of browser-controller

browser-controller scores 72/100 on our quality scale, 2582nd of 2,771 Automation skills we index.

Its MCP Server is 94 KB long, well organised into 62 sections with 13 code examples: long enough that it reads more like full documentation than a focused instruction file, which agents can find harder to follow.

It has 10 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
21/30
Structure
20/20
Description
12/15
Adoption
4/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 3 days ago, so browser-controller is actively maintained.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands.

Automated pattern scan on 2026-11-18. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

browser-controller compared with similar skills

All 4 of these similar skills score higher than browser-controller; compare them before choosing.

SkillScoreStarsUpdatedFormat
browser-controller (this skill)by compnew200672103d agoMCP Server
Agent-Reachby Panniantong100112.7k10d agoCLAUDE.md
rufloby ruvnet10082.0ktodayCLAUDE.md
headroomby headroomlabs-ai10079.9ktodayCLAUDE.md
CowAgentby zhayujie10048.0k1d agoCLAUDE.md

Frequently asked questions

How do I install browser-controller?
Run claude mcp add compnew2006 -- npx -y github:compnew2006/browser-controller. The install tabs above show the steps for each supported agent.
Which AI agents does browser-controller work with?
It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
Is browser-controller safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is browser-controller still maintained?
The repository was last updated 3 days ago, so browser-controller is actively maintained.
<p align="center"> <img src="https://cdn.jsdelivr.net/gh/compnew2006/browser-controller@51be0c2338b3ade9ebef1587b872cfa03dc45701/assets/logo.png" alt="Browser Controller" width="100" height="100" /> </p> <h1 align="center">Browser Controller</h1> <p align="center"> <strong>The missing piece in AI coding: your agent can now see your REAL browser.</strong> </p> <p align="center"> <a href="https://github.com/compnew2006/browser-controller/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/compnew2006/browser-controller/ci.yml?branch=main&label=CI&style=flat-square" alt="CI" /></a> <a href="https://github.com/compnew2006/browser-controller/releases"><img src="https://img.shields.io/badge/version-3.3.0-blue?style=flat-square" alt="v3.3.0" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow?style=flat-square" alt="License: MIT" /></a> <img src="https://img.shields.io/badge/node-22.18%2B%20%7C%2024.11%2B%20%7C%2026%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node 22.18+, 24.11+, or 26+" /> <img src="https://img.shields.io/badge/TypeScript-strict-blue?style=flat-square" alt="TypeScript strict" /> </p>

What this project solves

You ship a fix. Your agent says "done, please verify." You alt-tab to Chrome, navigate to the page, log in, click around, find the bug.

Your agent just wrote the code. It could also verify it. It already has your browser open right there. It just can't see it.

Now it can. Browser Controller gives any MCP-compatible AI agent (Cursor, Claude Desktop, Windsurf, …) direct control of the browser you already have open — your real sessions, your logins, your cookies. No headless browser, no fresh profile, no re-authentication.

Version 3.0 is a breaking release: 19 tools, one target locator, and text results with structured receipts for actions. See Migrating from 2.x.

Key capabilities

  • Multiple agents at once. Cursor can drive tab 10 while Claude drives tab 11 — both through one shared daemon, neither blocking the other.
  • Tab targeting, not "the active tab." Every page action names a tabId. Move your mouse, switch tabs, watch YouTube — the agent keeps working on the tab you told it to. It never hijacks the page you're reading.
  • Tab ownership without lock calls. A tab that browser_navigate opens for a session belongs to that session until it closes. Another session's call on that tab fails at once with TAB_LOCKED.
  • Per-tab isolation. Element refs are per page, and logs and network buffers are per tab. A ref from tab 10 can never click something in tab 20.
  • Per-tab concurrency. Two actions on the same tab serialize (no races); actions on different tabs run in parallel.
  • Agent-control shield. While a tool runs on a tab, you see a translucent blue inner frame and your input on that tab is blocked (mouse, keyboard, wheel). It disappears when the action finishes.
  • Visible agent cursor (optional). Switch on Show agent cursor in the popup's Settings and agent mouse actions draw a pointer that glides to its target first. Off by default.
  • Real, trusted input. Clicks, typing, keys, wheel and drags go through the Chrome DevTools Protocol, so the page sees isTrusted events and focus, Tab, Enter and autocomplete behave as they do for a person. There is no synthetic-event fallback: if the debugger cannot attach, input fails with DEBUGGER_UNAVAILABLE. The yellow "being debugged" banner shows while the debugger is attached.
  • One locator. target takes a ref (e12), text=Sign in, viewport coordinates (x,y), a CSS selector, or an accessible { role, name, nth? } object. Shadow roots and same-origin iframes are searched; cross-origin iframes are listed as not readable.
  • Honest results. A success is compact text. A failure is an isError result whose text is CODE: message, so the agent acts on the code instead of guessing.
  • Batches. browser_batch runs up to 50 tool calls in one round trip and stops at the first failing step (onError:"continue" runs the rest and names every failure).
  • The page is read after it settled. An action waits for the page to stop changing before the call returns, and a navigation waits for the page it loaded to draw, so the read that follows sees what the action produced, not the page before it. browser_wait {until:"stable"} waits for the same thing on demand.
  • A session can be fenced in. browser_tabs {action:"session"} opens the session for reading only (every call that changes something is refused), or isolates it (the agent touches the tabs it opened, and only those).
  • Console-style JavaScript. browser_evaluate accepts code as you'd type it in DevTools: top-level await, several statements with return, DOM nodes come back as readable descriptions. Over CDP, page CSP does not block it.
  • Console, network and mocks on demand. browser_logs reads a tab's console (uncaught errors with stacks) and its network requests, with response bodies on request. browser_mock answers or blocks one tab's requests, so the page really receives the fake response.
  • Frozen tabs don't freeze the agent. browser_navigate replaces a tab that stopped answering, and its result says so with a note: line naming the new tabId.
  • Several browsers. Every connected Chrome profile is its own connection. browser_tabs { action: "profiles" } lists stable IDs, local labels, the default, and whether each profile has open tabs without switching the session. Use the ID to select a profile; auto means the earliest-connected default. Set a recognizable local label in the extension's Settings.
  • Authenticated local connection. Token + enrollment secret, so no other local process can silently drive your browser — and after a one-time npm run setup:pairing the extension pairs itself. Everything stays on localhost — no cloud, no telemetry.
  • Versioned compatibility handshake. The daemon and extension advertise a protocol version and capabilities before tool traffic is accepted. A peer from before 3.0 is refused with an actionable error instead of producing unexplained timeouts.
  • Consoles and appliances. A hypervisor web client is an ordinary page to the agent, and the guest behind it is reachable through the same tools — the guest is a canvas, so it needs its own rules for reading, clicking and typing. The field guide is docs/esxi-vm-console-automation.md.

How it works

Three pieces, all on your machine. Nothing leaves localhost. The daemon control plane is hard-bound to 127.0.0.1; there is no supported remote/n8n listener.

flowchart LR
    subgraph Client["MCP client (Cursor / Claude / Windsurf)"]
        A["agent"]
    end

    subgraph Thin["thin MCP client — mcp-server/dist/index.js"]
        B["DaemonClient<br/>speaks MCP over stdio<br/>spawns daemon if not running<br/>gets its own sessionId"]
    end

    subgraph Daemon["daemon — single long-running process, owns port 7225"]
        C["daemon.ts<br/>multiplexes N clients → 1 extension<br/>sessions · rate limit · heartbeats"]
        D["bridge.ts (ExtensionBridge)<br/>HTTP /pair /status /kill<br/>WebSocket for the extension"]
    end

    subgraph Ext["Chrome extension (Manifest V3 service worker)"]
        E["connection.js<br/>pairing · reconnect backoff"]
        F["router.js<br/>tool dispatch"]
        G["tab-concurrency.js<br/>per-tab mutex · ownership · shield"]
        H["handlers/*<br/>interaction · inspection · evaluate · navigation · tabs<br/>logs · mock · emulate · cdp"]
        I["page-exec.js safeExec<br/>chrome.scripting func: — CSP-safe"]
        E --> F --> G --> H --> I
    end

    P["Page — your real sessions"]

    A -->|stdio MCP| B
    B -->|IPC socket + token| C
    C --> D
    D <-->|Authenticated WebSocket<br/>protocol version + capabilities| E
    I --> P

Key idea: the first time any agent runs, the thin client spawns a background daemon that owns port 7225 and the extension connection. Every subsequent agent (even from a different MCP client) connects to that same daemon over a local IPC socket and gets its own sessionId. The extension sees one stable connection and routes each call to the exact tab the caller specified.


Quick Start

The project is not on the Chrome Web Store or npm — you install it from this repository. Two parts: the MCP server (runs on your machine, talks to your AI agent) and the Chrome extension (sits in your browser, executes commands).

Prerequisites: Node.js 22.18+ within the 22.x line, 24.11+ within the 24.x line, or 26+; and Chrome/Chromium/Edge. CI tests the minimum and latest releases of the 22, 24, and 26 lines. Later Node.js major versions are allowed by engines but are not covered by the current CI matrix.

1. Clone & build

git clone https://github.com/compnew2006/browser-controller.git
cd browser-controller
npm install
npm run build        # compiles TypeScript → mcp-server/dist/

2. Load the Chrome extension

  1. Open chrome://extensions and enable Developer mode (toggle in the top right)
  2. Click Load unpacked and select the extension/ folder from the cloned repo
  3. Pin the Browser Controller icon to your toolbar

Gray dot = waiting for the daemon. Green = connected.

3. Add the MCP server to your client

Cursor: Settings → MCP → "Add new MCP server". Claude Desktop: edit claude_desktop_config.json. Windsurf: Settings → MCP. Any MCP-compatible client works.

Replace /path/to/browser-controller with the absolute path of your clone (Windows: use C:\\path\\to\\browser-controller\\mcp-server\\dist\\index.js):

{
  "mcpServers": {
    "browser-controller": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js"]
    }
  }
}
<details> <summary><b>Name your agent (shows in the popup)</b></summary>

By default the daemon names each connection after its parent IDE ("Cursor", "Claude", …). To override — e.g. when several agents share one IDE, or to label them by project — pass --agent <name> in the args. It takes priority over every auto-detection:

{
  "mcpServers": {
    "browser-controller": {
      "command": "node",
      "args": [
        "/path/to/browser-controller/mcp-server/dist/index.js",
        "--agent",
        "My Project Agent"
      ]
    }
  }
}

The name appears in the popup's Connected Agents list. (You can also set the MCP_AGENT_NAME env var — equivalent.) Reconnecting with the same name replaces the old entry, so IDE restarts don't pile up duplicates.

</details>

4. Pair the extension with the daemon

Run this once from the repo root:

npm run setup:pairing

Then click Reload on Browser Controller in chrome://extensions. The extension pairs itself — nothing to copy or paste. Green dot = you're connected. Your agent can now see your browser.

What the command sets up:

  • A small local helper (a Chrome native messaging host, mcp-server/dist/native-host.js), registered with every Chromium browser it finds: Chrome (stable, Beta, Canary), Chromium, Edge and Brave. It is a per-user install (on Windows, under HKCU\Software\…\NativeMessagingHosts) and needs no admin rights.
  • Chrome lets only this extension's ID start the helper. An unpacked extension's ID comes from its folder path; the command prints the ID it computed, and it must match the one shown in chrome://extensions. If you loaded the extension from another folder, pass its ID: npm run setup:pairing -- --extension-id <id>.
  • A launcher in .native-host/ that pins the current node, because a browser started from the Dock or Start menu does not see your shell's PATH.

The extension asks the helper only when the daemon refuses its secret — the fi

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars10
CategoryAutomation
Updated3d ago
Forks1

Languages

TypeScript

Trust signals

97/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 info