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`).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues