Parallel Browser MCP

parallel-browser-mcp

parallel-browser-mcp es un servidor MCP para automatización de navegadores en paralelo. Expone un modelo de sesión numérico sobre MCP para que un cliente pueda crear y controlar múltiples sesiones de navegador al mismo tiempo a través de múltiples proveedores de navegador.

Proveedores admitidos:

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

Cada sesión de navegador recibe un ID numérico como 1, 2, 3, y cada herramienta browser_* acepta un sessionId.

Características

• Múltiples sesiones de navegador concurrentes en memoria
• Abstracción de proveedor compartida entre Browserbase, Anchor Browser, Cloudflare Browser Run y Playwright local
• Herramientas de sesión MCP:
  • start_session
  • close_session
  • close_all_sessions
  • get_sessions
• Herramientas 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

Inicio rápido

corepack pnpm install
corepack pnpm build

Ejecútalo localmente con stdio:

node dist/index.js

Ejecútalo como CLI de paquete npm:

npx parallel-browser-mcp@latest

Configuración

Los ajustes específicos del proveedor se configuran a nivel de configuración del servidor MCP, no por llamada de herramienta.

El servidor lee la configuración en este orden:

1. BROWSER_MCP_CONFIG
2. BROWSER_MCP_CONFIG_PATH
3. valores predeterminados directos de entorno
4. valores predeterminados integrados

Forma de configuración recomendada:

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

Chromium con sigilo vía CloakBrowser

El proveedor playwright puede lanzar opcionalmente CloakBrowser en lugar de Chromium estándar para sesiones que necesiten evadir la detección de bots. Actívalo por configuración o por entorno:

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

PLAYWRIGHT_USE_CLOAKBROWSER=true

cloakbrowser es un peer opcional — instálalo solo cuando necesites sigilo:

npm install cloakbrowser

El binario de CloakBrowser (~200MB de Chromium con sigilo) se descarga automáticamente en el primer lanzamiento de sesión. Las configuraciones existentes de launchOptions / contextOptions siguen aplicándose, y el resto del proveedor se comporta de manera idéntica a Playwright estándar.

Credenciales requeridas por proveedor:

• playwright: ninguna
• browserbase: BROWSERBASE_API_KEY, más un projectId en la configuración o BROWSERBASE_PROJECT_ID
• anchor: ANCHOR_API_KEY
• cloudflare: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID

Valores predeterminados de entorno opcionales:

• 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 lanzar Chromium con sigilo vía CloakBrowser; requiere npm install cloakbrowser)

Instalación

Usa la configuración estándar a continuación en cualquier cliente MCP que admita 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"]}'

Flujo de ejemplo

1. Llama a start_session con { "provider": "playwright" }
2. Lee el id de sesión devuelto
3. Llama a browser_navigate con { "sessionId": 1, "url": "https://example.com" }
4. Llama a cualquier herramienta adicional browser_* con el mismo sessionId
5. Llama a close_session cuando termines

Desarrollo

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

Publicación

Este repositorio está configurado para publicarse como paquete npm:

• el punto de entrada de la CLI es parallel-browser-mcp
• las compilaciones de producción excluyen pruebas y scripts de smoke
• el paquete publicado solo incluye dist, README.md y .env.example

Antes de publicar:

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

Publicación con GitHub Actions:

• .github/workflows/publish.yml publica en npm al publicar una release en GitHub o mediante dispatch manual
• establece el secreto del repositorio NPM_TOKEN antes de usar el flujo de trabajo de publicación

Ejemplos

• examples/local contiene un paquete npm independiente que se conecta a parallel-browser-mcp con @langchain/mcp-adapters y ejecuta un agente LangChain contra el proveedor Playwright local.
• examples/browserbase contiene un paquete npm independiente que conecta LangChain al servidor MCP publicado con configuración de Browserbase y solicita al agente el uso de browser_screenshot.
• examples/anchor contiene un paquete npm independiente que conecta LangChain al servidor MCP publicado con configuración de Anchor y solicita al agente el uso de browser_snapshot.
• examples/cloudflare contiene un paquete npm independiente que conecta LangChain al servidor MCP publicado con configuración de Cloudflare Browser Run y solicita al agente el uso de browser_snapshot.
• El .npmignore raíz excluye el directorio completo de examples de la publicación npm.

Pruebas

El repositorio incluye:

• cobertura de unidades para carga de configuración, proveedores, comportamiento del registro, herramientas de sesión y herramientas representativas de navegador
• un script de smoke con Playwright local en src/smoke/localSmoke.ts

Notas

• start_session es intencionalmente pequeño. El comportamiento específico del proveedor pertenece a la configuración MCP, no a las entradas de las herramientas.
• El servidor registra en stderr para mantener stdout limpio para el tráfico JSON-RPC de MCP.
• Browserbase y Anchor Browser se normalizan a operaciones de página de Playwright después de la conexión, por lo que las herramientas de navegador permanecen agnósticas al proveedor.