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.

---

# Install core + an adapter
pnpm add @browserkit/core @browserkit/adapter-hackernews

# Log in once (for sites that need auth)
browserkit login hackernews

# 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"
    }
  }
}

---

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 Chromium  (authenticated)
  └── ...

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.

---

// 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/adapter-hackernews": {
      port: 3847,
    },
    "@someone/my-custom-adapter": {
      port: 3848,
      debugPort: 4848,      // optional: enables raw Playwright access via CDP
      authStrategy: "persistent",   // "persistent" | "storage-state" | "cdp-attach"
      rateLimit: { minDelayMs: 3000 },
    },