Browser Tool (MCP)

An MCP server for VS Code, from Nuanst, that lets AI agents (Claude Code, Copilot, or any MCP client) open any URL in a browser and interact with it.

• Headless browser — all automated actions (navigate, click, type, select, read, evaluate JS, screenshot) run on a headless Playwright Chromium ("the twin"), because webviews cannot script cross-origin pages. screenshot returns a real PNG of the page, so the agent — and you — see exactly what is there.

• Persistent session — a single browser context lives for the whole session, so cookies and SSO state persist across tool calls. A typical SSO login flows naturally: open_url → type credentials → click submit → wait_for dashboard → screenshot.

• Live view (optional) — set browserTool.browserTab to true and open_url/navigate also open the page in VS Code's integrated browser tab, so you can watch the agent work. Off by default (see Browser tab integration).

Installation

Install the Browser Tool (MCP) extension from the VS Code Marketplace. The extension registers the browser-tool MCP server with VS Code's MCP client (VS Code 1.104 or newer, which introduced the mcpServers contribution point).

The server is a plain Node.js program (Node >= 20). Any MCP client can run it:

npm install
npm run build
# Claude Code (user scope):
claude mcp add -s user browser-tool -- node /path/to/vscode-browser-tool/dist/server.js

or as a raw MCP client config:

{
  "mcpServers": {
    "browser-tool": {
      "command": "node",
      "args": ["/path/to/vscode-browser-tool/dist/server.js"]
    }
  }
}

Related MCP server: Browser Intelligence MCP

If the agent says the tools are unavailable

The Browser Tool output channel's "listening on …" line is the live-view pipe inside VS Code. It is not the MCP server. Claude connects to a separate process, node <extension>/dist/server.js.

Run Browser Tool: /doctor from the Command Palette. It starts that process, asks it to list its tools, and writes the result to the same output channel. A pipe that is listening does not mean the tools are connected.

Tools

Configuration

Environment variables (set on the MCP server entry):

By default the server uses Playwright's bundled Chromium. If it has never been downloaded on the machine, run npx playwright install chromium once.

Browser tab integration (optional live view)

Setting browserTool.browserTab to true makes open_url and navigate also open the page in VS Code's integrated browser tab. This is off by default and works like this:

• The MCP server is a plain Node process and cannot call the vscode API, so it talks to the extension host over a local named pipe (\\.\pipe\vscode-browser-tool on Windows, <tmpdir>/vscode-browser-tool.sock elsewhere).

• The extension host opens the tab with the proposed browser API (vscode.window.openBrowserTab) and, when available, attaches a CDP session so navigate steers the same tab (Page.navigate) instead of opening a new one.

• If the extension isn't loaded, VS Code isn't running, or the proposed API is missing in your VS Code version, requests are dropped silently — the headless twin is unaffected.

• One tab at a time; the tab is closed when you disable the setting again (or when the VS Code window reloads).

First-time setup (once): on a stable VS Code build the proposal must be enabled in argv.json ("enable-proposed-api": ["nuanst-one.vscode-browser-tool"]). Use the command "Browser Tool: Enable browser tab integration" (or the button in the warning it shows when you turn the setting on) — it opens argv.json via VS Code's own Configure Runtime Arguments command and copies a paste-ready snippet with the extension id to your clipboard. Then fully restart VS Code.

Because the browser API is a proposal, it may change shape or be removed in a future VS Code release. The extension feature-detects it and degrades to "no live view" rather than failing.

Example session

"open https://app.example.com with browser-tool, log in as me@example.com / <password>,
wait for the dashboard, and screenshot it."

The agent maps that to: open_url → type username → type password → click submit → wait_for → screenshot. The screenshot the agent returns is real evidence, not a guess.

Known limitations

• One page/context, no multi-tab. The browser renders headless at 1440×900, so you see the session through the screenshots and text the tools return.

• Auth flows the browser can't script (MFA/QR codes) must be completed through the tools (e.g. by typing the code into the login form).

• The browser tab live view uses a proposed VS Code API; it may not be available (or may change) depending on your VS Code version. Everything else is unaffected.

• get_text/eval_js results are truncated at 20,000 chars; get_html at 50,000.

Privacy

• No telemetry. The extension and its MCP server collect no usage data, send no analytics, and phone home to nothing. The only network traffic is the browser traffic generated by the pages themselves.

• Your credentials stay local. Cookies and SSO state live in a single local browser context for the session and are discarded when the server process ends (or on close).

Third-party content disclaimer

This extension is a browser automation layer: it opens, renders, and interacts with whatever URLs the user or the AI agent requests. The behaviour of those URLs is outside the scope of this extension and its maintainers' responsibility. Specifically:

• Content loaded from any site — including scripts, iframes, fonts, and tracking beacons embedded by that site or its third-party providers — executes or loads in the headless browser under the same rules as any other browser visit. We do not inspect, filter, or vouch for it.

• Data that a site receives (form submissions, logins, search queries, IP address) is governed by that site's own privacy policy, not by this extension.

• Agents may be pointed at arbitrary or untrusted URLs by design. Users are responsible for deciding which URLs to open and for using appropriate credentials in appropriate environments, exactly as with any other browser or Playwright-based tool.

Development

npm install
npm run build          # esbuild bundles -> dist/server.js + dist/extension.js
npm run typecheck      # tsc --noEmit

E2E smoke test

npm run testpage       # serves http://127.0.0.1:8765 in a terminal
node scripts/e2e.mjs   # drives the built server over stdio: 13 tools, click/type/eval/screenshot
node scripts/bridge-smoke.mjs   # fake pipe server: checks open_url/navigate cross the bridge

Or in an agent session: "open http://127.0.0.1:8765 with browser-tool, click #btn twice, read #count, and screenshot it."

Repository layout

License

MIT © Nuanst One GmbH

Source and issues: https://github.com/Nuanst-GmbH/viscose-browsertool