Skip to main content
Glama
Browser MCP for VS Code

Browser MCP for VS Code

by gerbillinae
README.md
# Browser MCP for VS Code

Lets Claude Code, or any MCP client, use the browser built into VS Code:
open pages, read them, take screenshots, click, type and run JavaScript. You
watch it happen in your editor, in a browser that has your cookies and
reaches your localhost.

Every VS Code window runs the extension, and they share one MCP server at
`http://127.0.0.1:3799/mcp`, so a single config entry reaches every window.

## How it works

```
Claude Code ──HTTP MCP──▶ hub window (holds port 3799) ──▶ its browser
                              │
                              └─WebSocket /peer─▶ other windows ──▶ their browsers
```

- **Election.** Each window tries to bind the port. The one that succeeds is
  the hub: it serves MCP at `/mcp`. The others join it at `/peer` and run the
  calls it forwards. When the hub window closes, the rest run the election
  again; one becomes the new hub and the others rejoin it. MCP sessions on
  the old hub end, and clients start new ones.
- **Which window a call goes to**, in order:
  1. the `window` argument, by name or id (`browser_windows` lists them);
  2. the window whose workspace folder holds the client's
     [roots](https://modelcontextprotocol.io/specification/latest/client/roots)
     (Claude Code's working directory), the deepest folder first;
  3. the window you focused most recently.

  Every result starts with the window used and why.
- **The browser** is VS Code's integrated browser, launched through an
  `editor-browser` debug session (VS Code 1.112+, built-in JavaScript
  debugger) whose `requestCDPProxy` gives a Chrome DevTools Protocol socket.
  One browser tab per window; `browser_open` opens it when it is closed.

## Tools

| Tool | |
|---|---|
| `browser_windows` | The windows, and which one is the default for you |
| `browser_open` | Open a URL and wait for it to load |
| `browser_screenshot` | PNG of the visible page, or `fullPage` |
| `browser_read` | The page's text, accessibility tree, or HTML |
| `browser_click` | By CSS selector or by visible text |
| `browser_type` | Into an input; optionally `clear` first and `submit` with Enter |
| `browser_eval` | A JavaScript expression's value, as JSON |
| `browser_console` | Recent console messages and uncaught exceptions |

## Setup

Install the `.vsix` (see Build), then reload VS Code. On start the
extension adds this to Claude Code's user config, `~/.claude.json`, if it
isn't there already:

```json
"mcpServers": { "vscode-browser": { "type": "http", "url": "http://127.0.0.1:3799/mcp" } }
```

Turn that off with `browserMcp.configureClaude`, or run **Browser MCP:
Register with Claude Code** to do it by hand. Start a new Claude Code
session afterwards. Claude Code connects when a session starts, so VS Code
must already be running.

Settings: `browserMcp.port` (default 3799; every window must use the same
one) and `browserMcp.configureClaude` (default on).

## Security

- Everything listens on `127.0.0.1` only.
- Requests whose `Host` isn't `127.0.0.1:<port>` or `localhost:<port>` are
  refused (DNS rebinding), and so are requests with an `Origin` header (web
  pages). MCP clients and windows send neither.
- Windows join the hub only with the secret in
  `~/.vscode-browser-mcp/secret`, which the first window creates.
- The MCP endpoint has no token: any program running as you can use it, as
  with any local MCP server. `browser_eval` runs any JavaScript in the open
  page, which is logged in as you wherever your browser is.

## Build

Needs Node 22.18+ (for running TypeScript tests directly).

```sh
npm install
npm test          # hub, peers, routing, security, config, with fake windows
npm run package   # type-check, bundle, and write vscode-browser-mcp-<version>.vsix
code --install-extension vscode-browser-mcp-0.1.0.vsix
```

`src/` splits into the parts with no VS Code dependency, tested in plain
Node (`protocol`, `routing`, `hub`, `node`, `tools`, `page`, `cdp`,
`claude-config`), and the two that need VS Code (`browser`, `extension`).