hyper-playwright
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hyper-playwright Open example.com/shop, add the first item to cart, and export the session as a test"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hyper-playwright
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 | |
AI agents and LLM-driven automation |
| |
Fresh machine, nothing to clone |
| |
Registering every local MCP client at once |
| |
Driving the browser over Streamable HTTP |
| |
Turning a session into a regression 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 |
| Open a URL, wait for settle, return Semantic Markdown. |
| Run several actions in one turn, with a |
| Open several URLs across pooled tabs, one merged report. |
| Re-distil the page, optionally with a PNG screenshot. |
| Read buffered console errors and failed requests. |
| Replay the session as a |
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,focusrun in parallel withPromise.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.dragtakes a destination ref invalue(e.g."e8");uploadtakes 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-mediaThis 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-mediainstall.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 |
| off | Show the browser window. |
| – | Attach to a running browser. |
| auto |
|
| off | Stop blocking images / fonts / media. |
| off | Permit |
|
| Persistent browser profile. |
|
| Concurrent swarm tabs (1–3). |
| stdio |
|
|
| HTTP port for |
All logs go to stderr. stdout carries JSON-RPC frames only — enforced by a unit test.
Web apps
npx hyper-playwright --transport http --port 8787Your 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. | — |
| Navigation is refused unless |
|
Constrained writes |
|
|
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 | ✅ | ✅ | ✅ |
| ✅ | ✅ | ✅ |
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 sitenpm 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
SPEC — full project specification
Playwright — the automation library underneath
License
MIT
Available Tools
6 toolsbrowser_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_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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Playwright browser automation — navigate, click, fill forms, extract, screenshot — 17 agent tools.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
A real browser for your agent: screenshots, page checks, Markdown and PDFs.
Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to i…
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceEnables 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-
- AlicenseNot gradedqualityCmaintenanceEnables 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 npm40Apache 2.0
- AlicenseBqualityBmaintenanceEnables 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.398 npmISC
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT