parallel-browser-mcp

parallel-browser-mcp는 병렬 브라우저 자동화를 위한 MCP 서버입니다. MCP를 통해 숫자 기반 세션 모델을 노출하여 하나의 클라이언트가 여러 브라우저 제공업체에 걸쳐 동시에 여러 브라우저 세션을 생성하고 제어할 수 있도록 합니다.

지원되는 제공업체:

• playwright (로컬 Chromium용)

• browserbase (@browserbasehq/sdk 사용)

• anchor (anchorbrowser 사용)

• cloudflare (Cloudflare Browser Run 사용)

각 브라우저 세션은 1, 2, 3과 같은 숫자 ID를 가지며, 모든 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
      }
    }
  }
}

제공업체별 필수 자격 증명:

• 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

설치

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 Code CLI를 사용하여 서버를 추가하세요:

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

제공업체 구성이 필요한 경우, 위 표준 구성을 사용하여 Claude MCP 구성에 환경 변수를 추가하세요.

Claude Desktop MCP 설치 절차를 따르고 로컬 MCP 구성 파일에 위 표준 구성을 사용하세요.

Codex CLI를 사용하세요:

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

또는 ~/.codex/config.toml에 다음을 추가하세요:

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

Copilot CLI 대화형 흐름을 사용하세요:

/mcp add

또는 ~/.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"
      }
    }
  }
}

Cursor Settings -> MCP -> Add new MCP Server로 이동한 다음 다음을 사용하세요:

• command: npx

• args: parallel-browser-mcp@latest

또는 위 표준 구성을 MCP 구성 편집기에 붙여넣으세요.

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

위 표준 구성을 사용하여 VS Code에서 MCP 설치 절차를 사용하거나 VS Code CLI로 설치하세요:

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 릴리스 게시 또는 수동 디스패치 시 npm에 게시합니다.

• 게시 워크플로우를 사용하기 전에 NPM_TOKEN 저장소 비밀을 설정하세요.

예시

• examples/local은 @langchain/mcp-adapters를 사용하여 parallel-browser-mcp에 연결하고 로컬 Playwright 제공업체에 대해 LangChain 에이전트를 실행하는 독립형 npm 패키지를 포함합니다.

• examples/browserbase는 LangChain을 Browserbase 구성으로 게시된 MCP 서버에 연결하고 에이전트가 browser_screenshot을 사용하도록 유도하는 독립형 npm 패키지를 포함합니다.

• examples/anchor는 LangChain을 Anchor 구성으로 게시된 MCP 서버에 연결하고 에이전트가 browser_snapshot을 사용하도록 유도하는 독립형 npm 패키지를 포함합니다.

• examples/cloudflare는 LangChain을 Cloudflare Browser Run 구성으로 게시된 MCP 서버에 연결하고 에이전트가 browser_snapshot을 사용하도록 유도하는 독립형 npm 패키지를 포함합니다.

• 루트 .npmignore는 npm 게시에서 전체 examples 디렉토리를 제외합니다.

테스트

저장소에는 다음이 포함됩니다:

• 구성 로딩, 제공업체, 레지스트리 동작, 세션 도구 및 대표적인 브라우저 도구에 대한 단위 커버리지

• src/smoke/localSmoke.ts의 로컬 Playwright 스모크 스크립트

참고

• start_session은 의도적으로 작게 설계되었습니다. 제공업체별 동작은 도구 입력이 아닌 MCP 구성에 속합니다.

• 서버는 stderr에 로그를 기록하여 stdout이 MCP JSON-RPC 트래픽을 위해 깨끗하게 유지되도록 합니다.

• Browserbase 및 Anchor Browser는 연결 후 Playwright 페이지 작업으로 정규화되므로 브라우저 도구는 제공업체에 구애받지 않습니다.