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

<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> <details> <summary>VS Code</summary>

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

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.