Skip to main content
Glama
parallel-browser-mcp

parallel-browser-mcp

by etairl

parallel-browser-mcp

npm version npm downloads

parallel-browser-mcp is an MCP server for parallel browser automation. It exposes a numeric session model over MCP so one client can create and control multiple browser sessions at the same time across multiple browser providers.

Supported providers:

  • playwright for local Chromium

  • browserbase via @browserbasehq/sdk

  • anchor via anchorbrowser

  • cloudflare via Cloudflare Browser Run

Each browser session gets a numeric ID like 1, 2, 3, and every browser_* tool accepts a sessionId.

Features

  • Multiple concurrent browser sessions in memory

  • Provider abstraction shared across Browserbase, Anchor Browser, Cloudflare Browser Run, and local Playwright

  • MCP session tools:

    • start_session

    • close_session

    • close_all_sessions

    • get_sessions

  • Browser tools:

    • browser_navigate

    • browser_go_back

    • browser_click

    • browser_fill

    • browser_fill_form

    • browser_screenshot

    • browser_snapshot

    • browser_hover

    • browser_drag

    • browser_select_option

    • browser_generate_locator

    • browser_get_page_structure

    • browser_evaluate

    • browser_keyboard_press

    • browser_keyboard_type

    • browser_mouse_move

    • browser_mouse_click_xy

    • browser_mouse_drag

    • browser_upload_file

    • browser_wait_for_selector

    • browser_wait_for_timeout

Related MCP server: open_browser_use

Quick Start

corepack pnpm install
corepack pnpm build

Run locally over stdio:

node dist/index.js

Run it as an npm package CLI:

npx parallel-browser-mcp@latest

Configuration

Provider-specific settings are configured at the MCP server configuration level, not per tool call.

The server reads config in this order:

  1. BROWSER_MCP_CONFIG

  2. BROWSER_MCP_CONFIG_PATH

  3. direct env defaults

  4. built-in defaults

Recommended config shape:

{
  "defaultProvider": "playwright",
  "providers": {
    "browserbase": {
      "projectId": "proj_123",
      "keepAlive": true
    },
    "anchor": {
      "recording": false
    },
    "playwright": {
      "launchOptions": {
        "headless": true
      },
      "useCloakBrowser": false
    }
  }
}

Stealth Chromium via CloakBrowser

The playwright provider can optionally launch CloakBrowser instead of vanilla Chromium for sessions that need to bypass bot detection. Enable it per-config or via env:

{
  "providers": {
    "playwright": { "useCloakBrowser": true }
  }
}
PLAYWRIGHT_USE_CLOAKBROWSER=true

cloakbrowser is an optional peer — install it only when you need stealth:

npm install cloakbrowser

The CloakBrowser binary (~200MB stealth Chromium) is downloaded automatically on the first session launch. Existing launchOptions / contextOptions continue to apply, and the rest of the provider behaves identically to standard Playwright.

Required credentials by provider:

  • playwright: none

  • browserbase: BROWSERBASE_API_KEY, plus a projectId in config or BROWSERBASE_PROJECT_ID

  • anchor: ANCHOR_API_KEY

  • cloudflare: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID

Optional env defaults:

  • BROWSERBASE_PROJECT_ID

  • BROWSERBASE_KEEP_ALIVE

  • BROWSERBASE_CONTEXT_ID

  • BROWSERBASE_PERSIST

  • PLAYWRIGHT_STORAGE_STATE_PATH

  • PLAYWRIGHT_EXECUTABLE_PATH

  • PLAYWRIGHT_CHANNEL

  • PLAYWRIGHT_USE_CLOAKBROWSER (true to launch stealth Chromium via CloakBrowser; requires npm install cloakbrowser)

Installation

Use the standard config below in any MCP client that supports stdio:

{
  "mcpServers": {
    "parallel-browser-mcp": {
      "command": "npx",
      "args": ["parallel-browser-mcp@latest"],
      "env": {
        "BROWSER_MCP_CONFIG": "{\"defaultProvider\":\"playwright\",\"providers\":{\"playwright\":{\"launchOptions\":{\"headless\":true}}}}",
        "BROWSERBASE_API_KEY": "your_browserbase_key",
        "ANCHOR_API_KEY": "your_anchor_key"
      }
    }
  }
}

Use the Claude Code CLI to add the server:

claude mcp add parallel-browser-mcp npx parallel-browser-mcp@latest

If you need provider configuration, add the environment variables in your Claude MCP config using the standard config above.

Follow the Claude Desktop MCP install flow and use the standard config above in the local MCP configuration file.

Use the Codex CLI:

codex mcp add parallel-browser-mcp npx "parallel-browser-mcp@latest"

Or add this to ~/.codex/config.toml:

[mcp_servers.parallel-browser-mcp]
command = "npx"
args = ["parallel-browser-mcp@latest"]

Use the Copilot CLI interactive flow:

/mcp add

Or add this to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "parallel-browser-mcp": {
      "type": "local",
      "command": "npx",
      "tools": ["*"],
      "args": ["parallel-browser-mcp@latest"],
      "env": {
        "BROWSER_MCP_CONFIG": "{\"defaultProvider\":\"playwright\",\"providers\":{\"playwright\":{\"launchOptions\":{\"headless\":true}}}}",
        "BROWSERBASE_API_KEY": "your_browserbase_key",
        "ANCHOR_API_KEY": "your_anchor_key"
      }
    }
  }
}

Go to Cursor Settings -> MCP -> Add new MCP Server, then use:

  • command: npx

  • args: parallel-browser-mcp@latest

Or paste the standard config above into the MCP config editor.

Add the server to .gemini/settings.json:

{
  "mcpServers": {
    "parallel-browser-mcp": {
      "command": "npx",
      "args": ["parallel-browser-mcp@latest"],
      "env": {
        "BROWSER_MCP_CONFIG": "{\"defaultProvider\":\"playwright\",\"providers\":{\"playwright\":{\"launchOptions\":{\"headless\":true}}}}",
        "BROWSERBASE_API_KEY": "your_browserbase_key",
        "ANCHOR_API_KEY": "your_anchor_key"
      }
    }
  }
}

Use the MCP install flow in VS Code with the standard config above, or install with the VS Code CLI:

code --add-mcp '{"name":"parallel-browser-mcp","command":"npx","args":["parallel-browser-mcp@latest"]}'

Example Flow

  1. Call start_session with { "provider": "playwright" }

  2. Read the returned session id

  3. Call browser_navigate with { "sessionId": 1, "url": "https://example.com" }

  4. Call any additional browser_* tool with the same sessionId

  5. Call close_session when done

Development

corepack pnpm install
corepack pnpm typecheck
corepack pnpm test
corepack pnpm test:coverage
corepack pnpm build
corepack pnpm smoke:local

Publishing

This repo is set up to publish as an npm package:

  • the CLI entrypoint is parallel-browser-mcp

  • production builds exclude tests and smoke scripts

  • the published package only includes dist, README.md, and .env.example

Before publishing:

corepack pnpm typecheck
corepack pnpm test
corepack pnpm build
npm pack --dry-run

GitHub Actions publishing:

  • .github/workflows/publish.yml publishes to npm on GitHub release publication or manual dispatch

  • set the NPM_TOKEN repository secret before using the publish workflow

Examples

  • examples/local contains a standalone npm package that connects to parallel-browser-mcp with @langchain/mcp-adapters and runs a LangChain agent against the local Playwright provider.

  • examples/browserbase contains a standalone npm package that connects LangChain to the published MCP server with Browserbase config and prompts the agent to use browser_screenshot.

  • examples/anchor contains a standalone npm package that connects LangChain to the published MCP server with Anchor config and prompts the agent to use browser_snapshot.

  • examples/cloudflare contains a standalone npm package that connects LangChain to the published MCP server with Cloudflare Browser Run config and prompts the agent to use browser_snapshot.

  • The root .npmignore excludes the full examples directory from npm publishing.

Testing

The repo includes:

  • unit coverage for config loading, providers, registry behavior, session tools, and representative browser tools

  • a local Playwright smoke script in src/smoke/localSmoke.ts

Notes

  • start_session is intentionally small. Provider-specific behavior belongs in MCP configuration, not tool inputs.

  • The server logs to stderr so stdout stays clean for MCP JSON-RPC traffic.

  • Browserbase and Anchor Browser are normalized to Playwright page operations after connection, so the browser tools stay provider-agnostic.

Available Tools

26 tools
browser_clickBrowser ClickC

Click an element by selector.

Inputs: selector (required), sessionId (required), timeout.

browser_dom_queryBrowser DOM QueryC

Query element presence, count, and state without waiting.

Inputs: selector (required), sessionId (required).

browser_dragBrowser DragC

Drag from one element to another.

Inputs: sessionId (required), sourceSelector (required), targetSelector (required), timeout.

browser_evaluateBrowser EvaluateC

Run JavaScript in the page context.

Inputs: script (required), sessionId (required), selector.

browser_fillBrowser FillC

Fill a field with text.

Inputs: value (required), selector (required), sessionId (required), timeout.

browser_fill_formBrowser Fill FormC

Fill multiple form fields.

Inputs: fields (required), sessionId (required).

browser_generate_locatorBrowser Generate LocatorC

Generate locator suggestions for an element.

Inputs: selector (required), sessionId (required).

browser_get_page_structureBrowser Get Page StructureC

Return a readable page structure summary.

Inputs: sessionId (required), maxDepth, selector, maxChildren.

browser_go_backBrowser Go BackC

Go back in browser history.

Inputs: sessionId (required).

browser_hoverBrowser HoverC

Hover over an element by selector.

Inputs: selector (required), sessionId (required), timeout.

browser_keyboard_pressBrowser Keyboard PressC

Press a keyboard key or key chord.

Inputs: key (required), sessionId (required).

browser_keyboard_typeBrowser Keyboard TypeC

Type text into the active page.

Inputs: text (required), sessionId (required), delay.

browser_mouse_click_xyBrowser Mouse Click XYC

Click at viewport coordinates.

Inputs: x (required), y (required), sessionId (required).

browser_mouse_dragBrowser Mouse DragD

Drag the mouse from one point to another.

Inputs: endX (required), endY (required), startX (required), startY (required), +1 more.

browser_mouse_moveBrowser Mouse MoveC

Move the mouse to viewport coordinates.

Inputs: x (required), y (required), sessionId (required).

browser_navigateBrowser NavigateD

Navigate the session page to a URL.

Inputs: url (required), sessionId (required).

browser_screenshotBrowser ScreenshotC

Capture a screenshot of the current page.

Inputs: sessionId (required), fullPage.

browser_select_optionBrowser Select OptionC

Select options in a select element.

Inputs: values (required), selector (required), sessionId (required), timeout.

browser_snapshotBrowser SnapshotC

Return a structured page snapshot.

Inputs: sessionId (required), maxDepth, selector, maxChildren.

browser_upload_fileBrowser Upload FileC

Upload files to a file input.

Inputs: selector (required), filePaths (required), sessionId (required).

browser_wait_for_selectorBrowser Wait For SelectorC

Wait for a selector to reach a state.

Inputs: selector (required), sessionId (required), state, timeout.

browser_wait_for_timeoutBrowser Wait For TimeoutC

Wait a fixed number of milliseconds.

Inputs: sessionId (required), milliseconds (required).

close_all_sessionsClose All SessionsA

Close all active browser sessions.

Inputs: no named parameters.

close_sessionClose SessionB

Close a browser session by numeric session ID.

Inputs: sessionId (required).

get_sessionsGet SessionsA

List all active browser sessions.

Inputs: no named parameters.

start_sessionStart SessionC

Start a browser session using the configured provider.

Inputs: provider, sessionName.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 26 tools

    Disambiguation3/5

    Most browser actions are individually clear, but several near-overlapping pairs exist: browser_snapshot, browser_get_page_structure, and browser_dom_query all describe page/DOM inspection, while browser_fill, browser_keyboard_type, browser_click, and browser_mouse_click_xy cover similar input territory. Descriptions reduce some ambiguity, but an agent could still easily select the wrong tool.

    Naming Consistency4/5

    Session tools follow a clean verb_noun pattern like start_session and close_session, while browser actions consistently use a browser_ prefix followed by descriptive verbs. The mixed prefixes are minor and the naming remains predictable and readable.

    Tool Count2/5

    With 26 tools, this server sits above the 25+ threshold and feels too heavy for a single MCP surface. Several mouse, keyboard, and DOM primitives could be consolidated or split into a separate server without losing functionality.

    Completeness4/5

    The toolset covers the core browser automation lifecycle well: navigation, DOM interaction, form filling, mouse/keyboard input, screenshots, uploads, waits, and session management. Notable gaps like tab/window management, cookies, and frame handling are missing, but agents can often work around them via browser_evaluate or separate sessions.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers