Saltar a contenido

Guía de configuración del MCP de Playwright

Esta guía resuelve los 4 incidentes de conexión que aparecieron repetidas veces al configurar el servidor MCP de Playwright para los skills de QA (qa-exploratory-test, etc.). Está pensada para que, si te encontrás con alguno de estos errores, sepas exactamente qué revisar y qué comando correr — sin tener que investigar de nuevo.

Requisitos previos

Esta guía usa los comandos de la CLI de Claude Code (claude mcp ...) como referencia, porque son los que están documentados hoy con este nivel de detalle. El archivo .mcp.json que se diagnostica en los incidentes de abajo es el mismo para Codex y Copilot — lo que cambia es el comando para listar/agregar/quitar el servidor MCP, que depende de la CLI o extensión de cada asistente. Si usás Codex o Copilot, buscá el comando equivalente en la documentación de esa herramienta; la lógica de cada incidente (qué está mal y por qué) es la misma.

  • Claude Code CLI instalado y funcionando — todos los comandos de esta guía (claude mcp ...) se corren desde ahí.
  • Node.js con npx disponible en el PATH — la config final levanta el servidor con npx @playwright/mcp@latest, así que npx tiene que poder resolver y descargar ese paquete.
  • Navegadores de Playwright instalados — si es la primera vez que usás Playwright en esta máquina, instalá los navegadores antes de configurar el MCP (esto instala Chromium, Firefox y WebKit): 
    npx playwright install

    **Importante: ** Si se esta usando vscode, el repositorio al que debe estar apuntando o mirando claude code, tiene que ser el repositorio bajo test. Sino puede que no encuentre el mcp al momento de configurar el bootstrap.

Cómo verificar el estado del MCP (siempre el primer paso)

claude mcp list

Buscá la línea de playwright. Puede darte 3 resultados:

  • ✓ Connected → el server está bien registrado (pero ver el Incidente 3 — "Connected" no siempre significa que las tools ya estén disponibles).
  • ✘ Failed to connect → ver Incidente 1.
  • Aparece dos veces (en scopes distintos) → ver Incidente 2.

Si claude mcp list muestra ✓ Connected pero las herramientas browser_* no aparecen cuando las buscás (ToolSearch en Claude Code, o simplemente no se pueden invocar), pasá directo al Incidente 3.

Incidente 1 — "Failed to connect" por nombre de paquete incorrecto

Configuración inicial (rota): 

{
  "mcpServers": {
    "playwright": {
      "command": "mcp-server-playwright",
      "args": ["--browser", "chromium"]
    }
  }
}

Qué pasa: 

claude mcp list
playwright: mcp-server-playwright --browser chromium - ✘ Failed to connect
mcp-server-playwright no es un paquete npm real — no existe con ese nombre. Por eso el proceso nunca arranca.

Variante del mismo síntoma: en vez de (o antes de) correr claude mcp list, puede que directamente veas este error en el chat al intentar usar una tool de Playwright: 

MCP error -32000: Connection closed
Es el mismo Incidente 1 visto desde el lado del cliente MCP: el proceso stdio del server nunca llegó a levantar (comando inexistente), entonces la conexión se cierra apenas se abre. Confirmalo corriendo: 
where mcp-server-playwright   # (o el comando que tengas configurado)
npm view @playwright/mcp version
Si el primero no encuentra nada y el segundo sí devuelve una versión, es este incidente — segui los mismos pasos de abajo.

Pasos a seguir:

  1. Eliminá la entrada rota:

    claude mcp remove playwright

  2. Volvé a agregarla con el paquete oficial (@playwright/mcp):

    claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium --isolated

    (el flag --isolated es para evitar el Incidente 4 — ver más abajo).

  3. Verificá:

    claude mcp list

Configuración final (correcta): 

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--browser", "chromium", "--isolated"]
    }
  }
}
Resultado esperado: playwright: npx @playwright/mcp@latest --browser chromium --isolated - ✓ Connected.

Incidente 2 — El servidor está duplicado en dos scopes distintos

Configuración inicial (rota): playwright definido a la vez en scope project (.mcp.json del repo) y en scope local (config personal), cada uno con un comando distinto (por ejemplo uno con el paquete roto del Incidente 1 y otro con el paquete correcto).

Qué pasa: 

[Warning] Server "playwright" is defined in multiple scopes with different
endpoints: project (mcp-server-playwright --browser chromium),
local (npx @playwright/mcp@latest). OAuth tokens are stored per endpoint...
Aunque uno de los dos esté bien, el conflicto de scopes hace que las tools browser_* no se registren nunca en la sesión.

Pasos a seguir:

  1. Confirmá en qué scopes está definido:

    claude mcp get playwright

  2. Dejá una sola definición. Sacá la del scope que no vas a usar (lo habitual es sacar la de project y quedarte con la de local, para no forzar la config a todo el equipo vía el repo):

    claude mcp remove playwright -s project

  3. Reiniciá VS Code por completo (cerrar y volver a abrir la ventana, no solo el chat) para que la sesión levante limpia.

Configuración final: una sola entrada de playwright, en un solo scope, con el comando correcto del Incidente 1. Verificá con claude mcp list que aparece una sola vez y sin warnings.

Incidente 3 — Las tools no aparecen aunque el server esté "Connected"

Configuración inicial: .mcp.json correcto, claude mcp list en ✓ Connected, pero al buscar las tools (browser_navigate, browser_click, etc.) no aparecen ninguna.

Qué pasa: la sesión de VS Code/Claude Code se abrió antes de que el servidor de Playwright quedara disponible (por ejemplo, lo configuraste o arreglaste con la sesión ya abierta). Las tools de un MCP nuevo no se cargan en caliente dentro de una sesión que ya estaba corriendo.

Pasos a seguir: 1. Cerrá todo VS Code (no solo la pestaña/ventana de chat). 2. Volvé a abrirlo. 3. Empezá una sesión nueva de Claude Code y volvé a intentar.

Configuración final: no cambia nada en el archivo de config — el fix es puramente "reiniciar sesión después de tocar la config del MCP". Regla general: cada vez que agregás, sacás o modificás un servidor MCP, reiniciá VS Code antes de volver a usarlo.

Incidente 4 — "Browser is already in use"

Configuración inicial (rota): 

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--browser", "chromium"]
    }
  }
}
(sin el flag --isolated)

Qué pasa: 

Error: Browser is already in use for
C:\Users\<user>\AppData\Local\ms-playwright-mcp\mcp-chrome-<hash>,
use --isolated to run multiple instances of the same browser
Pasa cuando dos sesiones de Claude Code (o una sesión vieja que quedó colgada) intentan controlar el mismo perfil de Chrome al mismo tiempo. Sin --isolated, todas las sesiones comparten un único perfil de navegador — la segunda que intenta usarlo choca con un lock.

Pasos a seguir:

  1. Si tenés otra sesión de Claude Code abierta usando Playwright, cerrala (o esperá a que termine) — eso libera el lock al toque.

  2. Para que esto no vuelva a pasar, agregá --isolated a los args del servidor:

    claude mcp remove playwright
claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium --isolated

  3. Reiniciá VS Code (ver Incidente 3) y probá de nuevo.

Configuración final (correcta): 

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--browser", "chromium", "--isolated"]
    }
  }
}
Con --isolated, cada sesión levanta su propio perfil de navegador aislado y pueden correr varias en paralelo sin pisarse.

Incidente 5 — "Browser ... is not installed" por versión desincronizada de @playwright/mcp@latest

Configuración inicial (rota): cualquier config que use @playwright/mcp@latest (la recomendada en esta guía), en una máquina donde ya había navegadores de Playwright instalados de una corrida anterior.

Qué pasa: 

Error: Browser "chrome-for-testing" is not installed; expected executable at
C:\Users\<user>\AppData\Local\ms-playwright\chromium-1237\chrome-win64\chrome.exe
Al usar @latest, cada corrida puede traer una versión distinta del paquete @playwright/mcp, y cada versión empaqueta una revisión distinta de Playwright (por lo tanto espera una revisión distinta de Chrome-for-Testing). Si en la máquina solo está instalada una revisión vieja (por ejemplo 1228) y el npx de esa corrida bajó una versión más nueva que pide la 1237, el navegador nunca abre — cualquier skill que dependa de browser_navigate queda bloqueada antes de llegar a la app.

Pasos a seguir:

  1. Instalá la revisión que el MCP actual espera, con el comando del propio MCP (no playwright install chromium, que puede traer una revisión distinta si el proyecto tiene otra versión de Playwright declarada en su package.json):

    npx @playwright/mcp@latest install-browser chrome-for-testing

  2. Si el error persiste, fijate qué revisión pide el mensaje de error y confirmá que esa carpeta exista en %LOCALAPPDATA%\ms-playwright\ (Windows) o ~/.cache/ms-playwright (Linux/Mac).

Cómo evitarlo a futuro: pinear una versión fija de @playwright/mcp en vez de @latest (ej. @playwright/mcp@0.x.y) en .mcp.json / qa-stack.yaml, para que la revisión esperada no cambie sola entre corridas. Si preferís seguir con @latest, correr npx @playwright/mcp@latest install-browser chrome-for-testing cada vez que actualices o reinstales dependencias — no solo la primera vez.

Configuración final recomendada (resuelve los 4 incidentes de una)

claude mcp add playwright -- npx @playwright/mcp@latest --browser chromium --isolated

Definida una sola vez, en un solo scope, con el paquete oficial @playwright/mcp y el flag --isolated. Después de configurarlo así:

  1. Reiniciá VS Code por completo.
  2. Verificá con claude mcp list → debe aparecer una sola vez como ✓ Connected.
  3. Empezá una sesión nueva y confirmá que las tools browser_* están disponibles antes de correr qa-exploratory-test u otro skill que dependa del browser.