Parallel Browser MCP

parallel-browser-mcp

parallel-browser-mcp é um servidor MCP para automação de navegador paralela. Ele expõe um modelo de sessão numérica via MCP, permitindo que um único cliente crie e controle várias sessões de navegador ao mesmo tempo em vários provedores de navegador.

Provedores suportados:

• playwright para Chromium local
• browserbase via @browserbasehq/sdk
• anchor via anchorbrowser
• cloudflare via Cloudflare Browser Run

Cada sessão de navegador recebe um ID numérico como 1, 2, 3, e cada ferramenta browser_* aceita um sessionId.

Recursos

• Múltiplas sessões de navegador simultâneas em memória
• Abstração de provedor compartilhada entre Browserbase, Anchor Browser, Cloudflare Browser Run e Playwright local
• Ferramentas de sessão MCP:
  • start_session
  • close_session
  • close_all_sessions
  • get_sessions
• Ferramentas de navegador:
  • 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

Início Rápido

corepack pnpm install
corepack pnpm build

Execute localmente via stdio:

node dist/index.js

Execute como CLI de pacote npm:

npx parallel-browser-mcp@latest

Configuração

As configurações específicas de cada provedor são definidas no nível de configuração do servidor MCP, não por chamada de ferramenta.

O servidor lê a configuração nesta ordem:

1. BROWSER_MCP_CONFIG
2. BROWSER_MCP_CONFIG_PATH
3. padrões diretos de variáveis de ambiente
4. padrões internos

Formato de configuração recomendado:

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

Chromium Stealth via CloakBrowser

O provedor playwright pode opcionalmente iniciar o CloakBrowser em vez do Chromium padrão para sessões que precisam contornar a detecção de bots. Ative-o por configuração ou via variável de ambiente:

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

PLAYWRIGHT_USE_CLOAKBROWSER=true

cloakbrowser é um peer opcional — instale-o apenas quando precisar de stealth:

npm install cloakbrowser

O binário do CloakBrowser (~200MB de Chromium stealth) é baixado automaticamente no primeiro lançamento de sessão. Os launchOptions / contextOptions existentes continuam valendo, e o restante do provedor se comporta de forma idêntica ao Playwright padrão.

Credenciais necessárias por provedor:

• playwright: nenhuma
• browserbase: BROWSERBASE_API_KEY, além de um projectId na configuração ou BROWSERBASE_PROJECT_ID
• anchor: ANCHOR_API_KEY
• cloudflare: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID

Padrões opcionais de variáveis de ambiente:

• BROWSERBASE_PROJECT_ID
• BROWSERBASE_KEEP_ALIVE
• BROWSERBASE_CONTEXT_ID
• BROWSERBASE_PERSIST
• PLAYWRIGHT_STORAGE_STATE_PATH
• PLAYWRIGHT_EXECUTABLE_PATH
• PLAYWRIGHT_CHANNEL
• PLAYWRIGHT_USE_CLOAKBROWSER (true para iniciar Chromium stealth via CloakBrowser; requer npm install cloakbrowser)

Instalação

Use a configuração padrão abaixo em qualquer cliente MCP que suporte 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"
      }
    }
  }
}

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

Fluxo de Exemplo

1. Chame start_session com { "provider": "playwright" }
2. Leia a sessão retornada id
3. Chame browser_navigate com { "sessionId": 1, "url": "https://example.com" }
4. Chame qualquer ferramenta browser_* adicional com o mesmo sessionId
5. Chame close_session quando terminar

Desenvolvimento

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

Publicação

Este repositório está configurado para publicar como pacote npm:

• o ponto de entrada da CLI é parallel-browser-mcp
• builds de produção excluem testes e scripts de smoke test
• o pacote publicado inclui apenas dist, README.md e .env.example

Antes de publicar:

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

Publicação via GitHub Actions:

• .github/workflows/publish.yml publica no npm na publicação de release do GitHub ou em dispatch manual
• defina o segredo do repositório NPM_TOKEN antes de usar o workflow de publicação

Exemplos

• examples/local contém um pacote npm autônomo que se conecta a parallel-browser-mcp com @langchain/mcp-adapters e executa um agente LangChain contra o provedor Playwright local.
• examples/browserbase contém um pacote npm autônomo que conecta o LangChain ao servidor MCP publicado com configuração do Browserbase e instrui o agente a usar browser_screenshot.
• examples/anchor contém um pacote npm autônomo que conecta o LangChain ao servidor MCP publicado com configuração do Anchor e instrui o agente a usar browser_snapshot.
• examples/cloudflare contém um pacote npm autônomo que conecta o LangChain ao servidor MCP publicado com configuração do Cloudflare Browser Run e instrui o agente a usar browser_snapshot.
• O .npmignore raiz exclui o diretório completo examples da publicação npm.

Testes

O repositório inclui:

• cobertura de testes unitários para carregamento de configuração, provedores, comportamento do registro, ferramentas de sessão e ferramentas representativas de navegador
• um script de smoke test local do Playwright em src/smoke/localSmoke.ts

Observações

• start_session é intencionalmente pequeno. O comportamento específico de provedor pertence à configuração MCP, não às entradas das ferramentas.
• O servidor registra logs em stderr para que o stdout permaneça limpo para o tráfego MCP JSON-RPC.
• Browserbase e Anchor Browser são normalizados para operações de página do Playwright após a conexão, então as ferramentas de navegador permanecem agnósticas em relação ao provedor.