Parallel Browser Mcp

parallel-browser-mcp

parallel-browser-mcp 是一款用于并行浏览器自动化的 MCP 服务。它通过 MCP 提供数字会话模型，让一个客户端能够同时创建和控制多个浏览器提供方上的多个浏览器会话。

支持的提供方：

• playwright：用于本地 Chromium
• browserbase：通过 @browserbasehq/sdk
• anchor：通过 anchorbrowser
• cloudflare：通过 Cloudflare Browser Run

每个浏览器会话都会分配一个数字 ID，例如 1、2、3，每个 browser_* 工具都接受 sessionId。

功能

• 在内存中维护多个并发浏览器会话
• 在 Browserbase、Anchor Browser、Cloudflare Browser Run 和本地 Playwright 之间共享提供方抽象
• MCP 会话工具：
  • start_session
  • close_session
  • close_all_sessions
  • get_sessions
• 浏览器工具：
  • 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

快速开始

corepack pnpm install
corepack pnpm build

通过 stdio 在本地运行：

node dist/index.js

将其作为 npm 包 CLI 运行：

npx parallel-browser-mcp@latest

配置

提供方专属设置在 MCP 服务配置级别进行配置，而非针对每次工具调用单独配置。

服务按以下顺序读取配置：

1. BROWSER_MCP_CONFIG
2. BROWSER_MCP_CONFIG_PATH
3. 直接使用环境变量默认值
4. 内置默认值

推荐的配置格式：

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

通过 CloakBrowser 使用隐身 Chromium

对于需要绕过机器人检测的会话，playwright 提供方可选择启动 CloakBrowser，而非原生 Chromium。可在每份配置中启用，也可通过环境变量启用：

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

PLAYWRIGHT_USE_CLOAKBROWSER=true

cloakbrowser 是可选的对等依赖——仅在需要隐身功能时安装：

npm install cloakbrowser

CloakBrowser 二进制文件（约 200MB 的隐身 Chromium）会在首次启动会话时自动下载。现有的 launchOptions / contextOptions 仍然适用，提供方的其他行为与标准 Playwright 完全相同。

各提供方所需的凭据：

• playwright：无
• browserbase：BROWSERBASE_API_KEY，以及配置中的 projectId 或 BROWSERBASE_PROJECT_ID
• anchor：ANCHOR_API_KEY
• cloudflare：CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID

可选的环境变量默认值：

• BROWSERBASE_PROJECT_ID
• BROWSERBASE_KEEP_ALIVE
• BROWSERBASE_CONTEXT_ID
• BROWSERBASE_PERSIST
• PLAYWRIGHT_STORAGE_STATE_PATH
• PLAYWRIGHT_EXECUTABLE_PATH
• PLAYWRIGHT_CHANNEL
• PLAYWRIGHT_USE_CLOAKBROWSER（设为 true，即可通过 CloakBrowser 启动隐身 Chromium；需要 npm install cloakbrowser）

安装

在支持 stdio 的任意 MCP 客户端中使用以下标准配置：

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

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

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

示例流程

1. 使用 { "provider": "playwright" } 调用 start_session
2. 读取返回的会话 id
3. 使用 { "sessionId": 1, "url": "https://example.com" } 调用 browser_navigate
4. 使用相同的 sessionId 调用其他任意 browser_* 工具
5. 完成后调用 close_session

开发

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

发布

此仓库已配置为发布 npm 包：

• CLI 入口点为 parallel-browser-mcp
• 生产构建会排除测试和冒烟测试脚本
• 发布的包仅包含 dist、README.md 和 .env.example

发布前：

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

GitHub Actions 发布：

• .github/workflows/publish.yml 会在发布 GitHub Release 或手动触发时发布到 npm
• 使用发布工作流前，请设置 NPM_TOKEN 仓库机密

示例

• examples/local 包含一个独立的 npm 包，它使用 @langchain/mcp-adapters 连接到 parallel-browser-mcp，并通过本地 Playwright 提供方运行 LangChain Agent。
• examples/browserbase 包含一个独立的 npm 包，它使用 Browserbase 配置将 LangChain 连接到已发布的 MCP 服务，并提示 Agent 使用 browser_screenshot。
• examples/anchor 包含一个独立的 npm 包，它使用 Anchor 配置将 LangChain 连接到已发布的 MCP 服务，并提示 Agent 使用 browser_snapshot。
• examples/cloudflare 包含一个独立的 npm 包，它使用 Cloudflare Browser Run 配置将 LangChain 连接到已发布的 MCP 服务，并提示 Agent 使用 browser_snapshot。
• 根目录的 .npmignore 会在发布 npm 包时排除整个 examples 目录。

测试

此仓库包含：

• 覆盖配置加载、提供方、注册表行为、会话工具和代表性浏览器工具的单元测试
• 位于 src/smoke/localSmoke.ts 的本地 Playwright 冒烟测试脚本

备注

• start_session 刻意保持精简。提供方特定的行为应在 MCP 配置中设置，而不是作为工具输入。
• 服务将日志写入 stderr，以确保 stdout 不受影响，可用于 MCP JSON-RPC 通信。
• Browserbase 和 Anchor Browser 连接后会统一为 Playwright 页面操作，因此浏览器工具不依赖特定提供方。