playwright-mcp-tabbed

playwright-mcp-tabbed

中文说明

A tab-aware Playwright MCP server for parallel agent workflows.

playwright-mcp-tabbed adds explicit tab_index support to Playwright MCP tools so multiple agents can operate on different tabs while sharing a single browser context and login session.

The Problem

The official @playwright/mcp model is centered around a shared active page. That is perfectly fine for single-agent flows, but it becomes fragile in concurrent workflows:

• Agent A selects tab 1
• Agent B selects tab 2
• Agent A's next action may accidentally run on tab 2

This project removes that shared active-tab assumption. Instead, each tool call can target a tab directly.

Typical Use Cases

playwright-mcp-tabbed is especially useful when browser automation is part of a larger agent workflow.

1. Batch bug fixing

One main agent logs in once, opens several tabs, and assigns one tab_index to each bug-fixing sub-agent. Every sub-agent can reproduce and verify its own issue in parallel without losing authentication state.

2. Multi-route regression checks

After a refactor, different agents can validate /orders, /wallet, /settings, and /users at the same time while staying inside the same logged-in admin session.

3. Side-by-side environment comparison

One tab points to the old app, another to the migrated app, and another to a staging environment. Agents can compare behavior or styling in parallel without repeatedly logging in.

4. Long workflows split across agents

Instead of forcing one agent to serialize a long browser journey, you can split related subflows into dedicated tabs and assign them to separate agents.

How It Works

• One browser instance
• One shared browser context
• Many tabs
• Every browser tool call can specify tab_index

This gives you:

• shared cookies and login state
• stable routing to the intended tab
• better fit for multi-agent orchestration

Key Features

• Adds tab_index (and stable tab_id) to nearly all browser tools
• Shares login state across tabs through one browser context for the same origin
• browser_context_info explains open tabs and reminds that localhost vs 127.0.0.1 use different cookies
• Optional PLAYWRIGHT_MCP_BASE_URL plus browser_navigate.base_url for relative paths like /dashboard
• browser_snapshot supports root_selector and max_chars to limit MCP payload size
• browser_click supports force, trial, and timeout (Playwright semantics)
• browser_network_requests supports limit and url_contains
• Keeps tool names close to the official Playwright MCP naming
• Works well in Cursor and similar MCP clients
• Designed for deterministic parallel agent behavior

Supported Tools

• browser_tabs Supports action: "list" | "new" | "close"; new accepts optional label; list includes tab_id per tab
• browser_context_info JSON summary of tabs, origins, and per-origin storage note
• browser_navigate
• browser_snapshot
• browser_take_screenshot
• browser_run_code
• browser_click
• browser_type
• browser_fill_form
• browser_file_upload
• browser_hover
• browser_select_option
• browser_press_key
• browser_wait_for
• browser_evaluate
• browser_navigate_back
• browser_network_requests
• browser_console_messages
• browser_resize
• browser_drag
• browser_handle_dialog
• browser_close
• browser_install

Tools that target a page accept either tab_index or tab_id (mutually exclusive). Prefer tab_id when sub-agents might race on tab creation order.

{ "tab_index": 1 }

{ "tab_id": "550e8400-e29b-41d4-a716-446655440000" }

Exceptions (no tab argument): browser_tabs, browser_close, browser_install, browser_context_info.

Environment

• PLAYWRIGHT_MCP_BASE_URL — optional default origin for relative URLs in browser_navigate (e.g. http://127.0.0.1:3000).
• PLAYWRIGHT_MCP_RECORD_VIDEO_DIR — optional writable directory for Playwright video recording. When set, each tab/page created in the shared browser context records a video. Video files are finalized when the page or browser context closes.

Differences From Official @playwright/mcp

• browser_tabs.select is intentionally not implemented
• tab switching is replaced by explicit tab_index routing
• the design target is concurrent agent execution, not a shared active-tab interaction model

Quick Start

Install via npm

npm install playwright-mcp-tabbed

Local install

git clone https://github.com/songofhawk/playwright-mcp-tabbed
cd playwright-mcp-tabbed && npm install

Add to Cursor

Add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "playwright-tabbed": {
      "command": "node",
      "args": ["/absolute/path/to/playwright-mcp-tabbed/dist/index.js"],
      "env": {
        "PLAYWRIGHT_MCP_RECORD_VIDEO_DIR": "/absolute/path/to/recordings"
      }
    }
  }
}

You can keep the official playwright server alongside it and only use playwright-tabbed for concurrent browser tasks.

If you do not need recording, omit env or leave PLAYWRIGHT_MCP_RECORD_VIDEO_DIR unset.

Agent skill: multi-tab orchestration

This repository includes an optional Agent Skill (for Cursor, Claude Code, and similar hosts) that documents how a main agent should create tabs, assign stable tab_ids to parallel sub-agents, and merge results—aligned with this MCP server.

• Path in repo: skills/playwright-tabbed-orchestration/ — contains SKILL.md and helper script scripts/resolve-base-url.js.
• Prerequisite: enable the playwright-tabbed MCP server in your client (see Add to Cursor).
• Note: The published npm package includes dist/ and skills/; you can copy from node_modules/playwright-mcp-tabbed/skills/playwright-tabbed-orchestration after install, or clone / use GitHub subpath (below) so paths stay stable.

What the skill covers

Resolve PLAYWRIGHT_BASE_URL, open N tabs, split URL/scenario lists, spawn N sub-agents (each scoped to one tab_id), then summarize. Full steps, guardrails, and a sub-agent prompt template are in SKILL.md.

Install the skill

Cursor — copy the folder into a skills directory your Cursor version recognizes, for example:

• Project-local: <your-project>/.cursor/skills/playwright-tabbed-orchestration/
• Or your user-level skills path per current Cursor documentation.

Claude Code — copy to:

• <repo>/.claude/skills/playwright-tabbed-orchestration/ (or the global skills location described in Anthropic’s docs).

OpenAI Codex — use the Codex skill-installer helper against this repository and the subpath below (adjust --ref if not on main):

python scripts/install-skill-from-github.py \
  --repo songofhawk/playwright-mcp-tabbed \
  --path skills/playwright-tabbed-orchestration

Equivalent tree URL:

https://github.com/songofhawk/playwright-mcp-tabbed/tree/main/skills/playwright-tabbed-orchestration

Restart Cursor / Codex (or reload skills) after copying or installing.

Helper: resolve-base-url.js

From the skill root:

cd skills/playwright-tabbed-orchestration
node scripts/resolve-base-url.js --help

Prints the site root URL from PLAYWRIGHT_BASE_URL (environment variable and/or git-root .env.local / .env / playwright.env.local). When resolving from project files, run with your terminal cwd on the application repository, or set PLAYWRIGHT_BASE_URL explicitly.

When To Use It

Use playwright-mcp-tabbed when:

• you have multiple sub-agents running browser tasks at the same time
• you need shared login state across those tasks
• you want deterministic browser routing without a shared current-tab pointer

Stay with the official @playwright/mcp when:

• you only have one agent
• your workflow is strictly sequential
• you do not need shared tabs across concurrent tasks

Current Limitation

This project intentionally favors explicit tab routing over active-tab semantics. If your tooling depends on browser_tabs.select, this server is not a drop-in replacement for that specific behavior.

License

MIT