browser-for-claude

An MCP server that gives Claude control of a real, headed Chromium browser via Playwright. It exposes a small set of tools — navigate, click, type, read text, screenshot, run JS, get URL, close — so Claude can drive a live browser session instead of just reading static content.

Features

• Isolated from your real browser — Claude never touches your everyday Chrome. See Privacy & Isolation below.

• Headed Chromium — the browser window is visible, not run in the background, so you can watch what Claude does in real time.

• Persistent session — the same browser/page stays open across tool calls until explicitly closed, so multi-step flows (navigate → click → type → screenshot) act on one continuous session.

• Minimal surface — eight tools, each a thin wrapper over one Playwright action.

Privacy & Isolation

This is not your everyday Chrome — it's a completely separate, throwaway browser instance:

• Different binary. Playwright launches its own bundled Chromium (installed via npx playwright install chromium), not the Chrome app on your machine.

• No shared profile. Each session starts from browser.newContext() — a brand-new, blank browsing context. It does not read your Chrome profile directory, so there's no access to your bookmarks, saved passwords, browsing history, extensions, or cookies.

• No Google account. Because the context starts blank, any site you're logged into in your real browser (Google, GitHub, etc.) shows up logged out here — Claude has no way to see or use your existing sessions.

• Nothing persists across restarts. browser_close (or the process exiting) discards the context entirely; nothing is written back to disk for next time.

In short: Claude can look at and click around a real, live web page, but it's working in its own sandboxed browser with a clean slate — never your personal one.

Tools

Requirements

• Node.js 20+

• npm

Setup

npm install
npx playwright install chromium
npm run build

Usage

Standalone

npm start

This starts the MCP server on stdio (dist/server.js). It's meant to be launched by an MCP client, not run interactively on its own.

With Claude Code

Add it as an MCP server, e.g. via a .mcp.json in your project:

{
  "mcpServers": {
    "browser-for-claude": {
      "command": "node",
      "args": ["dist/server.js"]
    }
  }
}

Claude Code will then discover the browser_* tools automatically.

Development

npm run build       # compile TypeScript (src -> dist)
npm run smoke-test   # launch a real browser and exercise every tool against example.com

The smoke test (test/smoke-test.ts) is an end-to-end check: it navigates to a real page, reads text, evaluates JS, takes a screenshot, and confirms that clicking a missing selector throws — all against a live Chromium instance rather than mocks.

Project structure

src/
  server.ts             MCP server: registers the browser_* tools
  browserController.ts  Playwright session management (launch/navigate/click/type/...)
test/
  smoke-test.ts         End-to-end smoke test against example.com

How it works

browserController.ts lazily launches a single headed Chromium browser, context, and page on first use, and keeps reusing them across tool calls until browser_close is called. A launch guard (launchInFlight) ensures concurrent tool calls can't race into launching two separate browser instances.

Caveats

• Only one browser session is supported at a time (no multi-tab/multi-context support).

• The isolation described above (see Privacy & Isolation) cuts both ways: if a task genuinely needs an already-logged-in site, you'll need to log in manually within the session first — there's no way to reuse credentials from your regular browser.

• Intended for local/trusted use — browser_evaluate runs arbitrary JavaScript in the page with no sandboxing beyond what the browser itself provides.

License

No license specified.