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.

corepack pnpm install
corepack pnpm build

node dist/index.js

npx parallel-browser-mcp@latest

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

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

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

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

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

/mcp add

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

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.