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:

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.