Browser Jet Pilot

Proudly announcing!

v1.0.1 — Live & Stable 💅

• API Key Authentication — secure your HTTP transport with API_KEY and X-API-Key header
• Constant-time auth — crypto.timingSafeEqual keeps the bad actors guessing
• Full test suite — 127 Vitest tests, zero flakes, CI-green on every push
• Developer tooling — ESLint, Prettier, Husky, lint-staged all tuned and humming
• CI/CD pipeline — typecheck → lint → format:check → test across Node 20/22/24
• Shader control tools — tame those heavy WebGL pages with browser_disable_shaders
• Bug fixes — SVG/MathML handling, proper browser cleanup, enhanced type safety

The extras that make it ✨

• browser_disable_shaders — block WebGL, freeze CSS animations, throttle requestAnimationFrame to ~1 FPS. Perfect for those pages that think they're a video game.
• browser_restore_shaders — bring the sparkle back (WebGL/RAF need a page reload to fully restore, nature of the beast)

What even is this?

A self-hosted MCP server for browser automation. Connect to your own Chromium via CDP — no subscription, no cloud, no weird per-session pricing. Just your browser, your infra, your rules.

Drop-in alternative to @browserbasehq/mcp. Same MCP protocol, none of the lock-in.

Features

• Connect to your existing browser via Chrome DevTools Protocol, or launch a fresh one managed by Playwright
• 19 deterministic tools — no LLM required for basic browser control
• MCP stdio transport — works with Claude Desktop, Cursor, any MCP client
• MCP HTTP transport — expose as a service with optional API key auth
• BrowserAgent — AI-powered autonomous agent (OpenAI, Anthropic, or custom endpoint)
• BrowserSkill — standardized skill interface for agent frameworks
• Multi-tab workflows — because one tab is never enough
• Screenshots — base64 PNG, full-page or single element
• Comprehensive testing — 127 tests, Vitest, coverage reports
• Pre-commit hooks — ESLint + Prettier gatekeep every commit

A little notice 🌸

I want you to understand that this repository contains a highly powerful toolset — exceptionally powerful.

It is shared in good faith, with the expectation that you will use these tools responsibly and for educational purposes, without causing harm to others. There are no guardrails, restrictions, or feature flags that would limit or alter their original capabilities.

As the saying goes, a weapon is only as dangerous as the hands that wield it. Power itself is neutral — its consequences are defined entirely by the intent and discipline of the user.

I won't go into detail about what could go wrong or the many ways these tools might be misused. If you found this repository while looking for that, you likely already know what you're doing — and I won't be the one to outline those paths. Instead, below you'll find guidance on how you should use these tools, along with the valuable, practical functionality they were designed to provide.

Keep in mind: these tools possess an extraordinary level of power, and that power is entirely in your hands.

If any damage occurs — whether through data leaks, automated actions, replay mechanisms, or otherwise — responsibility does not lie with the tools or this project. The sole accountable party is you. ¯\_(ツ)_/¯

Quick Start

1. Have a browser running with CDP

# With Xvfb + Chromium:
chromium --no-sandbox --remote-debugging-port=9222 --disable-gpu

# Or point at your existing Chromium (make sure it has --remote-debugging-port=9222)

2. Install & run

npm install
npm run build

# Stdio mode (Claude Desktop, Cursor, etc.)
node dist/index.js

# HTTP mode
node dist/index.js --port 3100

3. Hook it up to Claude Desktop

Drop this into your claude_desktop_config.json:

Platform	Config path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "CDP_URL": "http://localhost:9222"
      }
    }
  }
}

Docs (Mintlify)

Project docs live in docs/ — Mintlify format, cute and functional.

npm install          # includes Mint CLI as dev dependency
npm run docs:validate  # check it builds clean
npm run docs:links     # no dead links allowed
npm run docs:dev       # browse locally

CI/CD

Every push and PR goes through the wringer. The workflow lives at .github/workflows/ci.yml.

npm ci → typecheck → lint → format:check → test

Across Node 20, 22, and 24 — because we don't mess around. (Node 18 was politely asked to leave the party — vitest v4 needs styleText from node:util, which landed in 20.12.0.)

Development

Scripts at your fingertips

Command	What it does
npm run build	Compile TypeScript → dist/
npm run dev	Dev mode with tsx (hot, fast, lovely)
npm start	Run the built server
npm run agent	BrowserAgent CLI
npm run agent:seq	Deterministic tool sequence (no AI)
npm test	Run the full 127-test suite
npm run test:coverage	Tests + coverage report
npm run test:ui	Vitest UI (pretty!)
npm run lint	ESLint check
npm run lint:fix	ESLint auto-fix
npm run format	Prettier — make it pretty
npm run format:check	Prettier — is it pretty?
npm run typecheck	tsc --noEmit type safety check
npm run reliability:check	Full reliability test suite

Pre-commit magic

Husky + lint-staged keep the repo pristine:

• .ts, .tsx → ESLint + Prettier
• .json, .md, .yml → Prettier

npm install   # hooks set up automatically via the prepare script ✨

Docker

Compose (the easy way)

docker compose up -d --build
docker compose ps              # should say healthy 💚
curl http://localhost:3100/healthz

What you get:

• MCP endpoint: http://localhost:3100/mcp
• Health check: http://localhost:3100/healthz
• Built-in container healthcheck against /healthz

Quick smoke test:

npm run agent -- --server-url http://localhost:3100/mcp --sequence \
  browser_start "browser_navigate?url=https://example.com" \
  "browser_get_content?selector=body&type=text" browser_end

First build takes a bit — Playwright Chromium binaries install inside the container. Worth the wait.

Full reliability pass (health + lifecycle + extraction + multi-tab, 5x repeat):

npm run reliability:check
# or against a custom endpoint:
npm run reliability:check -- http://localhost:3100/mcp

Teardown

docker compose down

Plain Docker (no Compose)

docker build -t browser-jet-pilot:local .
docker run --rm -p 3100:3100 --shm-size=1g \
  -e PORT=3100 -e HOST=0.0.0.0 -e LAUNCH=true \
  browser-jet-pilot:local

External Chromium (CDP mode)

docker run --rm -p 3100:3100 --shm-size=1g \
  -e PORT=3100 -e HOST=0.0.0.0 -e LAUNCH=false \
  -e CDP_URL=http://host.docker.internal:9222 \
  browser-jet-pilot:local

On Linux where host.docker.internal doesn't resolve:

--add-host=host.docker.internal:host-gateway

Tools

Session

Tool	Description
browser_start	Connect to browser (or launch one). Call this first, always.
browser_end	Close the current session. Bye-bye!

Navigation

Tool	Parameters	Description
browser_navigate	url	Go to a URL
browser_new_tab	url?	Open a new tab
browser_list_tabs	—	List all open tabs
browser_switch_tab	index	Switch to tab by index
browser_get_info	—	Current URL, title, viewport

Interaction

Tool	Parameters	Description
browser_click	selector	Click an element
browser_fill	selector, value	Clear and fill an input
browser_type	selector, text, delay?	Type character by character
browser_select	selector, value	Select a dropdown option
browser_hover	selector	Hover over an element
browser_scroll	direction, amount?, selector?	Scroll page or element

Observation

Tool	Parameters	Description
browser_screenshot	fullPage?, selector?	Screenshot (base64 PNG)
browser_get_content	type?, selector?	Extract text or HTML
browser_evaluate	script	Run JavaScript in the page
browser_wait_for	selector, state?, timeout?	Wait for an element

Shader Control

Tool	Parameters	Description
browser_disable_shaders	webgl?, animations?, raf?	Block WebGL, freeze CSS animations, throttle RAF to ~1 FPS. Hit this before navigating to heavy shader pages.
browser_restore_shaders	—	Remove injected style overrides. WebGL/RAF need a page reload to fully come back — that's just how the browser works.

Configuration

CLI Flags

Flag	Env Var	Default	What it does
--port <n>	PORT	(stdio)	Port for HTTP transport
--host <host>	HOST	localhost	Bind address
--cdp-url <url>	CDP_URL	http://localhost:9222	CDP endpoint
--launch	LAUNCH=true	false	Launch a new browser instead of connecting
--browser-width <n>	BROWSER_WIDTH	1280	Viewport width
--browser-height <n>	BROWSER_HEIGHT	720	Viewport height

Environment

# .env file
CDP_URL=http://localhost:9222
LAUNCH=false
BROWSER_WIDTH=1280
BROWSER_HEIGHT=720
API_KEY=your-secret-api-key  # optional — locks down HTTP transport

API Key Auth 🔐

When running in HTTP mode, you can optionally gate the server behind an API key:

export API_KEY=your-secret-api-key

Then clients include it in the X-API-Key header:

curl -H "X-API-Key: your-secret-api-key" http://localhost:3100/mcp

The server uses crypto.timingSafeEqual for constant-time comparison — no timing attacks on our watch.

Examples

HTTP Transport

node dist/index.js --port 3100 --host 0.0.0.0
# → http://0.0.0.0:3100/mcp
# Connect any MCP client via Streamable HTTP transport

Launch Mode

No browser lying around? Let Playwright handle it:

node dist/index.js --launch --browser-width 1920 --browser-height 1080

How it stacks up to Browserbase MCP

Feature	Browserbase MCP	Browser Jet Pilot
Browser hosting	Browserbase cloud	Your container 💕
Cost	Per-session pricing	Free (your infra)
act (natural language)	Stagehand + LLM	Use deterministic tools or BrowserAgent
observe	Stagehand + LLM	browser_get_content + browser_screenshot
extract	Stagehand + LLM	browser_evaluate + browser_get_content
Screenshot	Via Stagehand	Native browser_screenshot
Tab management	Single page	Multi-tab ✨
Shader control	❌	browser_disable_shaders / browser_restore_shaders ✨
Data residency	Browserbase servers	Your server, your data

Architecture

flowchart LR
  subgraph App["Your Application"]
    BS["BrowserSkill"]
    BA["BrowserAgent (AI)"]
    MC["MCP Client<br/>(Claude Desktop, Cursor, etc.)"]
  end

  BS -->|MCP JSON-RPC| MB["Browser Jet Pilot<br/>(stdio or HTTP)"]
  BA -->|MCP JSON-RPC| MB
  MC -->|MCP JSON-RPC| MB

  MB --> PW["Playwright"]
  PW -->|CDP| CH["Your Chromium / Chrome"]

BrowserAgent (AI-Powered) 🤖

An autonomous agent that hooks into the MCP server and uses an LLM to figure out what tools to call, in what order, to accomplish your natural language task.

CLI

# AI-powered (needs OPENAI_API_KEY or ANTHROPIC_API_KEY)
npm run agent -- --server-url http://localhost:3100/mcp \
  "Go to start.gg and find the latest Tekken 7 tournament"

# Anthropic flavor
npm run agent -- --server-url http://localhost:3100/mcp \
  --ai-provider anthropic --ai-model claude-sonnet-4-20250514 \
  "Navigate to example.com and extract all links"

# Deterministic mode (no AI, straight tool sequence)
npm run agent -- --server-url http://localhost:3100/mcp --sequence \
  browser_start \
  "browser_navigate?url=https://example.com" \
  browser_screenshot \
  browser_end

Programmatic

import { BrowserAgent } from 'browser-jet-pilot/agent'

const agent = new BrowserAgent({
  serverUrl: 'http://localhost:3100/mcp',
  aiProvider: 'openai',
  aiModel: 'gpt-4o',
  // aiApiKey: 'sk-...',  // or set OPENAI_API_KEY
  maxSteps: 20,
})

// AI-powered task
const result = await agent.run(
  'Go to start.gg/tournament/12345 and get the bracket'
)
console.log(result.summary)
console.log(
  `Steps: ${result.steps.length}, Screenshots: ${result.screenshots.length}`
)

// Deterministic sequence
const result2 = await agent.executeSequence([
  { tool: 'browser_start' },
  { tool: 'browser_navigate', args: { url: 'https://example.com' } },
  { tool: 'browser_screenshot' },
])

await agent.disconnect()

Agent Config

Option	Env Var	Default	What it does
serverUrl	—	—	MCP server HTTP endpoint
serverCommand	—	node	MCP server command (stdio)
serverArgs	—	['./dist/index.js']	MCP server args (stdio)
aiProvider	—	openai	openai or anthropic
aiModel	—	gpt-4o	LLM model name
aiApiKey	OPENAI_API_KEY	—	Your API key
aiBaseUrl	—	provider default	Custom endpoint
maxSteps	—	30	Safety limit per task

BrowserSkill (Agent Framework Integration) 🧩

A standardized skill wrapper ready to drop into any agent framework. Comes with quick helper methods and automatic screenshot saving.

Programmatic

import { BrowserSkill } from 'browser-jet-pilot/skill'

const skill = new BrowserSkill({
  serverUrl: 'http://localhost:3100/mcp',
  saveScreenshots: true,
  screenshotDir: './screenshots',
})

await skill.init()

// AI-powered browser task
const result = await skill.execute(
  'Go to start.gg and extract tournament data',
  { workDir: './workspace' }
)
console.log(result.summary) // "Found 3 tournaments..."
console.log(result.files) // ['./screenshots/step-3-1712...png']
console.log(result.metadata) // steps, duration, tool calls

// Quick helpers (deterministic, no AI needed)
const page = await skill.goto('https://example.com')
const content = await skill.read('https://example.com', '#main-content')
const { base64, file } = await skill.capture('https://example.com', true)
const links = await skill.extract(
  'https://example.com',
  'Array.from(document.querySelectorAll("a")).map(a => ({text: a.innerText, href: a.href}))'
)

await skill.destroy()

Skill Interface

interface SkillResult {
  success: boolean
  summary: string
  files: string[] // saved screenshot paths
  data?: any // parsed JSON from last step
  metadata: {
    steps: number
    screenshots: number
    totalDuration: number
    toolCalls: Array<{ tool: string; args: Record<string, unknown> }>
  }
}

Requirements

• Node.js >= 20.12.0
• Chromium with --remote-debugging-port=9222 (or launch mode)
• For Playwright browser launch: npx playwright install chromium

License

MIT

designed, written and coded solely by head and from 💜 for you 0xabadbabe (Sudo Qt — jet'aime)