browserkit

An open-source framework for building site-specific MCP servers that operate over real, authenticated user browser sessions — running locally on your machine.

Turn your logged-in browser sessions into composable, testable AI tools.

---

Why local sessions?

Cloud browser automation services work by running browsers on their servers and asking you to re-authenticate there. That model works well for anonymous or company-owned accounts, but breaks down for personal ones — you wouldn't hand your LinkedIn, Gmail, or bank credentials to a third-party server.

browserkit takes the opposite approach: your machine is already authenticated everywhere. It reuses the sessions that exist on your laptop right now, runs all browsers locally, and never sends cookies or credentials over the network. The AI gets access to your real identity on the web; nothing leaves localhost.

The trade-off is intentional — browserkit is single-user and local-only by design. If you need a cloud fleet or multi-tenant access, this is not that tool.

---

Quick Start

# Install core + adapters
pnpm add @browserkit-dev/core @browserkit-dev/adapter-hackernews @browserkit-dev/adapter-linkedin

# Log in once per authenticated site (opens a browser window)
browserkit login linkedin

# Start the daemon
browserkit start --config browserkit.config.js

Configure your MCP client (Cursor, Claude Desktop, etc.):

{
  "mcpServers": {
    "browserkit-hackernews": { "url": "http://localhost:3847/mcp" },
    "browserkit-linkedin":   { "url": "http://localhost:3848/mcp" }
  }
}

---

Available Adapters

Package	Site	Auth	Tools
@browserkit-dev/adapter-hackernews	Hacker News	none	get_top, get_new, get_ask, get_show, get_comments
@browserkit-dev/adapter-linkedin	LinkedIn	required	get_person_profile, get_company_profile, get_company_posts, search_people, search_jobs, get_job_details, get_feed
@browserkit-dev/adapter-reddit	Reddit	none	get_subreddit, get_thread, search, get_user

---

How It Works

Each adapter runs as a dedicated MCP HTTP server on its own port. Multiple AI agents can connect concurrently — requests are serialized per adapter to protect the browser session.

AI Agent (Cursor / Claude / custom)
         ↓ HTTP MCP
browserkit daemon
  ├── hackernews  :3847  headless Chromium  (public, no auth needed)
  ├── linkedin    :3848  headless Chrome    (authenticated, uses real Chrome)
  └── ...

Browsers run fully headless by default — no window, no Dock icon. They only surface visibly during login (browserkit login) or when you explicitly switch to watch or pause mode.

---

Configuration

// browserkit.config.js
export default {
  host: "127.0.0.1",        // bind address (non-localhost requires bearerToken)
  basePort: 3847,           // first adapter auto-assigns from here
  bearerToken: process.env.BROWSERKIT_TOKEN,  // optional auth

  adapters: {
    // key = npm package name (no naming convention required)
    "@browserkit-dev/adapter-hackernews": {
      port: 3847,
    },
    "@browserkit-dev/adapter-linkedin": {
      port: 3848,
      channel: "chrome",    // use real Chrome — avoids bot detection on login
    },
    "@someone/my-custom-adapter": {
      port: 3849,
      debugPort: 4849,      // optional: enables raw Playwright access via CDP
      authStrategy: "persistent",   // "persistent" | "storage-state" | "cdp-attach" | "extension"
      rateLimit: { minDelayMs: 3000 },
    },
  },
};

---

CLI

browserkit start [--adapter <pkg>] [--port <n>] [--config <path>]
browserkit login <site>           # one-time login (opens browser)
browserkit status                 # show running adapters
browserkit config cursor          # generate Cursor MCP settings JSON
browserkit create-adapter <name>  # scaffold a new adapter package

---

Tools on Every Adapter Server

Each adapter exposes its own domain tools plus these auto-registered tools:

Domain tools (adapter-specific)

Whatever the adapter declares — e.g. get_feed, search_people, get_top.

Browser control (auto-registered, bypass lock)

Tool	Description
set_mode	Switch between headless, watch (visible), paused (user control)
take_screenshot	Capture current page as inline image — AI can see it directly
get_page_state	URL, title, mode, CDP endpoint for raw access
navigate	Navigate to a URL (within lock)
health_check	Browser alive, login status, selector validation report

---

Browser Modes

headless  →  fully invisible, automation runs normally (default)
watch     →  browser becomes visible, automation continues (optional slowMoMs)
paused    →  browser visible, tool calls queue — user has manual control

Switch modes via the set_mode MCP tool from any AI agent.

---

Extension Mode (Chrome via Playwriter)

Some sites aggressively block automated browsers — Google, LinkedIn, and others detect Playwright's Chromium and refuse login. Extension mode solves this by running adapter tools directly in your real, logged-in Chrome browser instead of launching a separate Patchright instance.

AI Agent (Cursor / Claude)
    ↓ HTTP MCP
browserkit daemon
    ├── hackernews  :3847  headless Patchright  (default — no login needed)
    └── linkedin    :3848  your Chrome          (extension mode — inherits your session)
                              └── Playwriter relay → Chrome extension → authenticated tab

Setup

1. Install the Playwriter Chrome extension from the Chrome Web Store.

2. Install the playwriter npm package:

pnpm add playwriter

3. Click the Playwriter extension icon on the tab you want browserkit to use. The icon turns green when active.

4. Configure the adapter to use extension mode:

// browserkit.config.js
export default {
  adapters: {
    "@browserkit-dev/adapter-linkedin": {
      authStrategy: "extension",  // use Chrome extension backend
      // extensionPort: 19988,    // optional — Playwriter's default
    },
    "@browserkit-dev/adapter-hackernews": {
      // defaults to "persistent" — headless Patchright as normal
    },
  },
};

5. Start the daemon — no browserkit login needed:

browserkit start

How it works

browserkit starts Playwriter's local WebSocket relay server and connects Patchright to it via connectOverCDP(). The Chrome extension uses chrome.debugger to forward CDP commands to your active Chrome tab. Adapter tools receive a full Playwright Page object — page.goto(), page.evaluate(), page.route(), screenshots, locators — all work normally.

The Playwriter extension automatically creates a tab group named "playwriter" for automation tabs, and all new tabs open in the background (active: false) so your current tab is never interrupted.

What changes vs. default mode

	Default (persistent)	Extension mode
Browser	Headless Patchright	Your real Chrome
Auth	browserkit login	Already logged in
Bot detection	Patchright anti-detection	None needed (real Chrome)
Headless	Yes	No
Tab groups	N/A	Green "playwriter" group
set_mode	headless/watch/paused	Not applicable

Accepted tradeoffs

• Chrome-only (not Brave, Arc, Firefox)
• chrome.debugger shows "Chrome is being controlled by automated test software" banner on attached tabs
• Requires Chrome to be open and the Playwriter extension active
• Shared browser: automation runs in your Chrome (CPU/memory shared with your browsing)

---

Raw Playwright Access (via CDP)

When debugPort is configured, get_page_state returns a cdpUrl. External agents — Claude Code, Cursor, custom scripts — can attach to the already-authenticated browser session and run arbitrary Playwright code:

// Script written by Claude Code, executed via shell
const { chromium } = require('playwright');

// Attach to the running session — already logged in, no auth needed
const browser = await chromium.connectOverCDP("http://127.0.0.1:4848");
const context = browser.contexts()[0];
const page = context.pages()[0];

// Full Playwright API — write any automation
await page.goto("https://my-site.com/data");
const results = await page.$$eval(".row", (els) => els.map((el) => el.textContent?.trim()));
console.log(JSON.stringify(results));

await browser.disconnect(); // disconnect only — session stays alive

Pattern: AI writes a script to /tmp/script.js, runs it via shell, reads stdout.

Enable in config: debugPort: adapterPort + 1000 (e.g. adapter on 3848 → debugPort 4848).

---

Building an Adapter

Reference implementations

• browserkit-dev/adapter-hackernews — public site, no auth, 5 tools, full 4-layer test suite. The simplest starting point.
• browserkit-dev/adapter-linkedin — authenticated site, 7 tools, innerText extraction strategy + ARIA-anchor feed scraping. Good reference for adapters that need login and work against DOM-churning JS apps.

Scaffold

npx @browserkit-dev/core create-adapter my-site
cd adapter-my-site
pnpm install

This generates the full package structure: src/index.ts, src/selectors.ts, vitest.config.ts, package.json, README.md.

SiteAdapter interface

import { defineAdapter } from "@browserkit-dev/core";
import { z } from "zod";
import type { Page } from "playwright";

export default defineAdapter({
  // ── Required ────────────────────────────────────────────────────────────
  site: "my-site",                          // unique ID, becomes the MCP server name
  domain: "my-site.com",                    // used for profile scoping
  loginUrl: "https://my-site.com/login",    // where to navigate for login flow

  async isLoggedIn(page: Page): Promise<boolean> {
    // Return true when the page shows an authenticated state.
    // Called before every tool call. If it returns false, browserkit
    // triggers the human handoff flow (opens browser, waits for login).
    // For public sites (no auth), always return true.
    return page.getByRole("navigation", { name: "user menu" }).isVisible({ timeout: 3000 });
  },

  tools: () => [ /* see below */ ],

  // ── Optional ────────────────────────────────────────────────────────────
  rateLimit: { minDelayMs: 2000 },          // min delay between consecutive tool calls

  selectors: {                              // exported CSS selectors for health_check reporting
    mainContent: ".main-content",           // health_check validates these on the live page
    loginButton: "button[data-testid=login]",
  },
});

Tool definition

tools: () => [
  {
    name: "get_data",
    description: "Get data from my-site",

    // Zod schema — validated before handler is called
    inputSchema: z.object({
      query: z.string().describe("Search query"),
      limit: z.number().int().min(1).max(50).default(10),
    }),

    // handler receives: the live authenticated Page + validated input
    async handler(page: Page, input: unknown) {
      const { query, limit } = mySchema.parse(input); // use schema.parse for type safety

      await page.goto(`https://my-site.com/search?q=${encodeURIComponent(query)}`);
      await page.waitForSelector(".result", { timeout: 10_000 });

      const results = await page.evaluate(({ sel, n }) => {
        return Array.from(document.querySelectorAll(sel))
          .slice(0, n)
          .map((el) => el.textContent?.trim() ?? "");
      }, { sel: ".result", n: limit });

      // Return value must have this shape:
      return {
        content: [{ type: "text" as const, text: JSON.stringify(results, null, 2) }],
        // isError: true  — set this if the tool failed but you want to return a message
      };
    },
  },
],

Tool handler contract:

• page is a live Playwright Page — already navigated, already authenticated
• input is the validated result of your Zod schema — always parse it inside the handler for type safety
• Return { content: [{ type: "text", text: string }] } for text results
• Return { content: [{ type: "image", data: base64, mimeType: "image/png" }] } for images
• Return { content: [...], isError: true } to signal a tool-level error without crashing

Testing your adapter

Use @browserkit-dev/core/testing to write tests that spin up a real in-process server:

// tests/mcp-protocol.test.ts
import { describe, it, expect, beforeAll, afterAll } from "vitest";
import myAdapter from "../src/index.js";
import { createTestAdapterServer, createTestMcpClient } from "@browserkit-dev/core/testing";

let server, client;

beforeAll(async () => {
  server = await createTestAdapterServer(myAdapter);
  client = await createTestMcpClient(server.url);
}, 30_000);

afterAll(async () => {
  await client.close();
  await server.stop();
});

it("get_data returns results", async () => {
  const result = await client.callTool("get_data", { query: "test" });
  expect(result.isError).toBeFalsy();
  const data = JSON.parse(result.content[0].text);
  expect(Array.isArray(data)).toBe(true);
});

createTestAdapterServer launches the adapter with an isolated temp data directory (avoids pidfile conflicts with a running daemon). createTestMcpClient connects via the real MCP HTTP transport — the same path used by Cursor and Claude Desktop.

For a complete 4-layer example, see browserkit-dev/adapter-hackernews/tests/.

Publish

pnpm build
npm publish --access public

Users add the package name to browserkit.config.js — no naming convention required. Any npm package name works.

---

Planned Adapters

Community contributions welcome — use browserkit create-adapter <name> to scaffold, see Building an Adapter above.

Site	Why browserkit	Proposed tools	Status
Twitter / X	API is $100/mo+; most personal accounts have no API access	get_feed, search, get_thread, get_bookmarks, get_dms, get_lists	open
Amazon	No consumer API at all	get_orders, search_products, get_product, get_wishlist, track_price	open
Airbnb	No public API; useful for trip-planning agents	search_listings, get_listing, get_bookings, get_messages	open
Google Maps	Places API is expensive per-call; browser is free	search_nearby, get_place, get_reviews, get_directions	open

If you're interested in building one, open an issue on browserkit-dev/browserkit to coordinate.

---

Architecture

See ARCH.md for full architecture details.

Key properties:

• Session-persistent: maintains auth across tool calls and process restarts
• Site-specific: deterministic selector-based tools, not DOM-guessing agents
• MCP-native: each adapter is a standard HTTP MCP server
• Human-in-the-loop: opens browser for login, 2FA, CAPTCHA
• Multi-client: multiple AI agents can connect to the same adapter concurrently

---

License

MIT