parallel-browser-mcp

![npm version](https://www.npmjs.com/package/parallel-browser-mcp) ![npm downloads](https://www.npmjs.com/package/parallel-browser-mcp)

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

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:

BROWSER_MCP_CONFIG
BROWSER_MCP_CONFIG_PATH
direct env defaults
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"
      }
    }
  }
}

<details> <summary>Claude Code</summary>

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. </details>

<details> <summary>Claude Desktop</summary>

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

<details> <summary>Codex</summary>

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"]

</details>

<details> <summary>Copilot</summary>

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"
      }
    }
  }
}

</details>

<details> <summary>Cursor</summary>

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. </details>

<details> <summary>Gemini</summary>

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"
      }
    }
  }
}

</details>

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"]}'

</details>

Example Flow

Call start_session with { "provider": "playwright" }
Read the returned session id
Call browser_navigate with { "sessionId": 1, "url": "https://example.com" }
Call any additional browser_* tool with the same sessionId
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.

Parallel Browser MCP