Skip to main content
Glama

hyper-playwright

npm version Node version License: MIT

Tools | CLI flags | Security

hyper-playwright is a zero-setup, token-efficient Model Context Protocol server for Playwright — with in-page multi-cursor swarm execution.

Standard @playwright/mcp behaves like a slow single-cursor remote control: the LLM sends one action, waits for a full ARIA tree dump, reads thousands of noisy tokens, then sends the next action. hyper-playwright moves the spatial reading and the parallel execution into the browser runtime: pages load with bloat blocked, elements arrive as compact Semantic Markdown with stable [eN] references, and batches plus multi-tab swarms complete in a single turn.

Related MCP server: Fast Playwright MCP

Get Started

Choose the path that fits your workflow:

Best for

Command

MCP server

AI agents and LLM-driven automation

npx -y hyper-playwright

One-click install

Fresh machine, nothing to clone

curl -fsSL https://raw.githubusercontent.com/vamsireddy4/hyper-playwright/main/install.sh | bash

Install script

Registering every local MCP client at once

./install.sh

Web apps

Driving the browser over Streamable HTTP

npx hyper-playwright --transport http --port 8787

Exported tests

Turning a session into a regression test

browser_export_test


MCP server

The server boots in under 50 ms — the stdio transport connects before the browser is even launched. Chromium starts lazily on the first browser_navigate call, auto-detecting a locally installed Chrome or Edge and falling back to bundled Chromium.

Setup

Add to your MCP client configuration:

{
  "mcpServers": {
    "hyper-playwright": {
      "command": "npx",
      "args": ["-y", "hyper-playwright"]
    }
  }
}

Headed mode with images and fonts enabled:

{
  "mcpServers": {
    "hyper-playwright": {
      "command": "npx",
      "args": ["-y", "hyper-playwright", "--headed", "--allow-media"]
    }
  }
}

Attach to a browser you already have open (Chrome → Inspect → remote debugging port):

{
  "mcpServers": {
    "hyper-playwright": {
      "command": "npx",
      "args": ["-y", "hyper-playwright", "--cdp", "9222"]
    }
  }
}

How it works

Ask your agent to interact with any web page. It sees the page as compact Semantic Markdown instead of a verbose ARIA tree:

<untrusted_web_content>
# Aurora Store

**URL:** https://example.com/shop

## Navigation
- [e1] "Home" (link)
- [e2] "Catalog" (link)

## Forms
- [e4] "Email address" (textbox, type=text)
- [e5] "Plan" (combobox)
</untrusted_web_content>

It acts on those [eN] references with browser_batch, fans multi-page work out with browser_swarm, and converts the finished session into a runnable test with browser_export_test — roughly 70% fewer tokens per turn than a raw ARIA dump.


Tools

Six tools cover the whole workflow:

Tool

What it does

browser_navigate

Open a URL, wait for settle, return Semantic Markdown.

browser_batch

Run several actions in one turn, with a + / - diff.

browser_swarm

Open several URLs across pooled tabs, one merged report.

browser_snapshot

Re-distil the page, optionally with a PNG screenshot.

browser_debug

Read buffered console errors and failed requests.

browser_export_test

Replay the session as a @playwright/test spec.

Batch actions

{
  "actions": [
    { "action": "fill",   "ref": "e4", "value": "agent@example.com" },
    { "action": "check",  "ref": "e6" },
    { "action": "select", "ref": "e5", "value": "pro" },
    { "action": "click",  "ref": "e7" }
  ]
}
  • fill, type, check, uncheck, hover, focus run in parallel with Promise.all, each with its own cloned ghost cursor.

  • Everything else — click, dblclick, drag, upload, select, press, scroll, reload, back, forward, dialogAccept, dialogDismiss, wait — runs sequentially, since it can navigate or invalidate references.

  • drag takes a destination ref in value (e.g. "e8"); upload takes file path(s); reload / back / forward / dialog actions take no ref.

  • A failed click reports what is actually in the way (⛔ blocked by [e9] "Cookie banner"), and repeating one action with no DOM change raises a loop warning.

Multi-tab swarm

{
  "tasks": [
    { "url": "https://a.example", "query": "price", "label": "Product A" },
    { "url": "https://b.example", "query": "stock", "label": "Product B" }
  ],
  "isolated": false
}

At most 3 tabs globally and 2 per domain, with 80–200 ms jitter against 429s and CAPTCHAs. Set isolated: true for authenticated or mutating work — each task then runs in a throwaway context cloned from the current storageState.


Export tests

{ "title": "Buy a pair of headphones", "path": "./tests/buy.spec.ts" }

Every recorded action becomes a role + name locator so the spec survives re-renders:

import { test, expect } from '@playwright/test';

test('Buy a pair of headphones', async ({ page }) => {
  await page.goto('https://example.com/shop');
  await page.getByRole('textbox', { name: 'Email address' }).fill('agent@example.com');
  await page.getByRole('button', { name: 'Add to cart' }).click();
});

Install / uninstall

Two scripts, one command each. Both are idempotent and safe to re-run.

One-click install — no clone needed, a single command fetches the repo and runs the installer:

curl -fsSL https://raw.githubusercontent.com/vamsireddy4/hyper-playwright/main/install.sh | bash
# with flags: ... | bash -s -- --headed --allow-media

This clones to ~/hyper-playwright (override with HP_DEST) and then runs the same steps as ./install.sh. Re-running it pulls the latest code and reinstalls.

From a checkout:

./install.sh                     # headless (default)
./install.sh --headed            # visible browser window
./install.sh --headed --allow-media

install.sh installs dependencies, builds the CLI, links it onto your PATH as hyper-playwright, and registers the server with every MCP client it finds — Claude Code, opencode and Claude Desktop.

./uninstall.sh          # removes the binary and every client registration
./uninstall.sh --purge  # also deletes ~/.hyper-playwright (cookies + logins)

Without --purge the persistent browser profile is deliberately kept.


CLI flags

Flag

Default

Purpose

--headed

off

Show the browser window.

--cdp <url|port>

–

Attach to a running browser.

--browser <name>

auto

chrome, msedge or chromium.

--allow-media

off

Stop blocking images / fonts / media.

--allow-file-urls

off

Permit file:// navigation.

--profile <dir>

~/.hyper-playwright/profile

Persistent browser profile.

--max-tabs <n>

3

Concurrent swarm tabs (1–3).

--transport <name>

stdio

stdio or http.

--port <n>

8787

HTTP port for --transport http.

All logs go to stderr. stdout carries JSON-RPC frames only — enforced by a unit test.

Web apps

npx hyper-playwright --transport http --port 8787

Your app connects to POST http://127.0.0.1:8787/mcp. Keep it on 127.0.0.1 unless you have added your own auth/TLS layer.


Security

Page content can try to talk the agent into doing something it should not. Three defences are on by default.

Defence

Behaviour

Opt-out

Injection filtering

Text matching common injection patterns is dropped from the payload; the count is reported.

—

file:// blocked

Navigation is refused unless --allow-file-urls is passed.

--allow-file-urls

Constrained writes

browser_export_test writes only inside the working directory or a temp directory.

--allow-write-anywhere

Every payload is wrapped in <untrusted_web_content> tags so the host can tell page-derived text apart from instructions.


Cross-platform support

macOS

Windows

Linux

Headless / headed

✅

✅

✅

Auto-detect Chrome / Edge

✅

✅

✅

Bundled Chromium fallback

✅

✅

✅

--cdp attach

✅

✅

✅

Sandbox flags

–

–

auto

Sandbox flags (--no-sandbox, --disable-setuid-sandbox, --disable-dev-shm-usage) apply only on Linux. The persistent profile lives at ~/.hyper-playwright/profile. Process cleanup uses taskkill /F /T on Windows and a process-group SIGKILL elsewhere.

Development

npm install
npm run build       # tsup → dist/index.js (single ESM file) + dist/lib.js
npm run typecheck   # tsc --noEmit, zero errors
npm test            # 22 unit tests (node:test, no extra dependencies)
npm run verify      # full end-to-end MCP suite against a local test site

npm run verify boots the real binary over stdio and exercises the handshake, navigation, batch execution, obstacle diagnostics, overlay handling, swarm execution, isolated contexts, screenshots, debug buffering, test export, media blocking, the security guardrails, and --cdp attachment.

Resources

License

MIT

Available Tools

6 tools
browser_batchRun a batch of page actionsA

Execute several actions on the current page in one turn. Fill/check/hover/type/focus run in PARALLEL with cloned multi-cursors; everything else runs SEQUENTIALLY because it can change the page. Drag takes a destination ref in "value" (e.g. value "e8"); upload takes file path(s); reload/back/forward/dialogAccept/dialogDismiss take no ref. Returns a per-action report, obstacle diagnostics for failed clicks, and a compact "+ / -" diff.

Inputs: actions (required), url.

browser_debugRead buffered browser diagnosticsA

Return buffered console errors, uncaught page errors and failed network requests collected since the browser started. Use this when a page renders incorrectly or an action fails for an unknown reason.

Inputs: clear.

browser_export_testExport the session as a Playwright testA

Convert every action performed in this session into a runnable @playwright/test spec file, using role+name locators so the test survives re-renders. Returns the file contents, and optionally writes them to disk.

Inputs: path, title.

browser_navigateNavigate to a URLA

Open a URL in the browser, wait for the page to settle, then return a compact Semantic Markdown snapshot. Interactive elements are listed with stable [eN] references (e.g. "[e12] Search (button)"). Use those references with browser_batch to act on the page. Ads, trackers and heavy media are blocked by default.

Inputs: url (required), scope, timeout, waitUntil.

browser_snapshotSnapshot the current pageA

Re-distil the current page and return a fresh Semantic Markdown snapshot with updated [eN] references. Also able to capture a PNG screenshot (useful for applications or vision workflows).

Inputs: scope, fullPage, screenshot.

browser_swarmRun multiple URLs in parallelA

Open several URLs concurrently across a pool of up to 3 recycled worker tabs (max 2 per domain) and return one merged Markdown report. Use this instead of sequential navigations when a task spans multiple pages, lists or links. Each task can carry a "query" to scope the extracted content.

Inputs: tasks (required), isolated, maxCharsPerTask.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool targets a distinct phase of browser automation: navigate (single URL), swarm (multi-URL), batch (actions), snapshot (refresh state), debug (diagnostics), export_test (test generation). The only mild overlap is navigate vs. swarm, but the descriptions clearly separate one-page from many-page use.

    Naming Consistency4/5

    All names share the browser_ prefix and snake_case, so the family is obvious. There is a slight mix of noun-style labels (snapshot, batch, swarm) with verb-style ones (navigate, debug), but the pattern stays readable and predictable.

    Tool Count5/5

    Six tools cover the whole browse-act-inspect-export loop without filler. Each has a clear role, and no operation feels redundant or missing from the set.

    Completeness4/5

    Navigation, batched interaction, state refresh, diagnostics, multi-page scraping and test export give near-full lifecycle coverage. Minor gaps exist, such as explicit session/tab cleanup or a standalone screenshot/download control, but snapshot's PNG option and batch actions cover most needs.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables browser automation and web interaction through structured accessibility snapshots using Playwright. Provides fast, deterministic web page interaction without requiring screenshots or vision models.
      10,908,336 npm
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables token-optimized browser automation with Playwright, featuring batch execution, diff detection, and advanced filtering to reduce token usage by 70-95% while providing LLM-friendly structured accessibility snapshots instead of screenshots.
      5,001 npm
      40
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables browser automation and API testing for AI agents using Playwright and Chrome DevTools Protocol, with numbered element references, Set-of-Mark screenshots, flow recording/replay, element memory, captcha handoff, and HTTP API test suites.
      39
      8 npm
      ISC
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to run Playwright-compatible browser automation against Chromium with persistent profiles, proxy matching, humanized interactions, and npm, Docker, stdio, or Streamable HTTP deployment.
      280 npm
      MIT