Cómo usar Claude Code con Playwright MCP: Guía de configuración completa

¿Qué es Playwright MCP?

El servidor Playwright MCP le da a cualquier cliente del Protocolo de Contexto de Modelo superpoderes de automatización de navegadores. En lugar de pedirle a una IA que “mire” píxeles, el servidor devuelve snapshots estructurados de accesibilidad de la página, y el modelo interactúa con elementos por ID de referencia. Eso hace que el bucle sea rápido, determinista y libre de la sobrecarga de modelos de visión. Funciona con VS Code, Cursor, Windsurf, Claude Desktop, Claude Code y cualquier otro cliente MCP.

Para Claude Code en particular, esto significa que el agente en tu terminal ahora puede abrir un navegador, hacer clic, rellenar formularios, simular solicitudes de red, capturar pantallas e incluso ejecutar scripts personalizados de Playwright — todo impulsado por indicaciones en lenguaje natural.

Requisitos previos

Antes de comenzar, asegúrate de tener:

• Node.js 18 o más reciente instalado
• Claude Code instalado e iniciado sesión (ejecuta claude en tu terminal para verificar)
• Una terminal en la que te sientas cómodo trabajando

Eso es todo — Playwright MCP descarga sus propios binarios de navegador en la primera ejecución.

¿Listo para hacer crecer tu negocio?

Comienza tu prueba gratuita hoy y ve resultados en días.

Solicitar demo Iniciar sesión

Configurar la integración de Playwright MCP

Conectar Playwright MCP a Claude Code es un comando único. Sigue estos pasos para conectarlo:

Agregar el servidor Playwright MCP

Abre tu terminal y ejecuta:

claude mcp add playwright npx @playwright/mcp@latest

Esto registra un nuevo servidor MCP llamado playwright que Claude Code lanza a través de npx siempre que necesita herramientas de navegador. La primera invocación descarga el paquete y los binarios de navegador requeridos, así que dale un minuto la primera vez.

Verificar la conexión

Inicia una nueva sesión de Claude Code y ejecuta el comando /mcp:

claude

/mcp

Deberías ver playwright listado como un servidor conectado, junto con las herramientas que expone (navegación, hacer clic, escribir, capturas de pantalla, simulación de red y más).

Opcional: Usar una configuración JSON en su lugar

Si prefieres editar archivos de configuración directamente, el mismo servidor se puede agregar a ~/.claude.json (o un archivo .mcp.json con alcance de proyecto) usando el formato MCP estándar:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

Reinicia Claude Code después de editar el archivo y el servidor aparecerá en /mcp.

Tu primera automatización de navegador en Claude Code

Con el servidor conectado, tus indicaciones ahora pueden controlar un navegador real. Intenta la interacción canónica de primer paso de la documentación de Playwright:

Navega a https://demo.playwright.dev/todomvc y agrega algunos elementos de tareas.

Claude Code abrirá el navegador, solicitará un snapshot de accesibilidad de la página, ubicará la entrada por su referencia de elemento, escribirá cada tarea y confirmará el resultado en tu terminal.

Atención sobre qué navegador se abre: por defecto esto lanza Chromium en modo con interfaz gráfica. Para cambiarlo, agrega banderas a los args en tu configuración MCP y reinicia Claude Code: --headless para ocultar la ventana, o --browser=firefox|webkit|msedge para cambiar motores.

Cómo funcionan los snapshots de accesibilidad

Cuando se ejecuta una herramienta de Playwright MCP, devuelve un snapshot estructurado de la página — roles de elementos, contenido de texto e IDs de referencia — en lugar de píxeles. Claude lee el snapshot y usa referencias como ref=e5 para escribir en el cuadro de texto o ref=e10 para activar la casilla de verificación. Sin empuje de píxeles, sin selectores CSS frágiles — solo estado de página estructurado en el que el modelo puede razonar.

Únete a nuestro boletín

Obtén los últimos consejos, tendencias y ofertas gratis.

Dirección de correo electrónico

Suscribirse

Capacidades principales que puedes usar desde Claude Code

Una vez que Playwright MCP está conectado, las mismas indicaciones que le darías a un compañero funcionan en Claude Code:

• Navegación: “Ir a example.com,” “volver atrás,” “recargar la página.”
• Hacer clic y escribir: “Haz clic en el botón Enviar,” “rellena el campo de correo electrónico con test@example.com .”
• Capturas de pantalla: “Toma una captura de pantalla de la sección de precios.”
• Teclado y ratón: Presiona teclas, pasa el ratón, arrastra y suelta.
• Pestañas y diálogos: Abre nuevas pestañas, cambia entre ellas, acepta o descarta ventanas emergentes.
• Monitoreo de red: “Enumera las solicitudes realizadas desde la carga de la página.”
• Simulación de API: “Simula el punto final /api/users para devolver una matriz vacía.”
• Estado de almacenamiento: Guarda sesiones autenticadas en un archivo y recárgalas más tarde.

Para flujos de trabajo que necesitan más de una llamada a herramienta única, puedes pedirle a Claude Code que invoque browser_run_code y ejecute un script de Playwright en línea — útil para aserciones, extracción de datos o cualquier cosa que se beneficie de algunas líneas de código imperativo.

Opciones de configuración útiles

Playwright MCP tiene un puñado de banderas que vale la pena conocer. Agréguelas a la matriz args en tu configuración (o al comando claude mcp add después de --).

Modo sin interfaz gráfica

El navegador se ejecuta con interfaz gráfica por defecto para que puedas ver qué está sucediendo. Para ejecutar sin interfaz gráfica — útil para CI o shells remotos — pasa --headless:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless"
      ]
    }
  }
}

Elegir un navegador

Cambia motores con la bandera --browser. Los valores soportados son chrome, firefox, webkit y msedge:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--browser=firefox"
      ]
    }
  }
}

Modos de perfil

Playwright MCP soporta tres modos de perfil:

• Persistente (predeterminado): El estado de inicio de sesión y las cookies persisten entre sesiones.
• Aislado: Pasa --isolated para comenzar cada sesión de nuevo, opcionalmente sembrada con --storage-state.
• Extensión de navegador: Pasa --extension para conectarte a tus pestañas de navegador existentes a través de la extensión Playwright MCP Bridge.

Servidor HTTP independiente

Si necesitas ejecutar un navegador con interfaz gráfica en algún lugar sin pantalla conectada (o desde un worker del IDE), lanza el servidor por separado y conéctate a través de HTTP.

Abre una segunda terminal — déjala ejecutándose durante toda la sesión — e inicia el servidor allí:

npx @playwright/mcp@latest --port 8931

Mantén esa terminal abierta. Es lo que expone el navegador en localhost:8931 para que puedas ver la sesión en tu propio navegador y para que Claude Code tenga algo a lo que conectarse. Cerrar la terminal apaga el servidor.

Luego, en la terminal donde ejecutas Claude Code, apunta a él actualizando tu configuración:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

Flujos de trabajo prácticos que vale la pena copiar

Una vez que Playwright MCP está conectado, Claude Code puede manejar andamiaje de pruebas de extremo a extremo, reproducciones de errores, verificaciones de simulación de API, auditorías de páginas y pruebas de humo de lanzamiento — cualquier cosa que implique controlar un navegador e informar de vuelta.

Dos cosas hacen que esas indicaciones funcionen en la práctica. Primero, un CLAUDE.md en la raíz de tu proyecto que documente tu URL de ensayo, credenciales de demostración y cualquier convención que el agente deba seguir — sin él, “inicia sesión como el usuario de demostración” no tiene nada a lo que aferrarse. Segundo, si quieres que Claude Code extraiga contexto de problemas o tickets, conecta un segundo servidor MCP para eso — el servidor GitHub MCP es la opción común. Omite ambos y Claude Code te preguntará (razonablemente) qué es el problema #482.

¿Por qué emparejar Claude Code con Playwright MCP?

Algunas razones por las que esta combinación es difícil de superar:

• Nativa de terminal: Todo sucede donde ya trabajas. Sin cambio de contexto a un corredor de pruebas separado.
• Primero la accesibilidad: Los snapshots superan a las capturas de pantalla en velocidad y confiabilidad, y funcionan sin un modelo de visión.
• Playwright real debajo: Cualquier cosa que puedas hacer con Playwright en código, puedes hacerla aquí — multi-navegador, simulación de red, estado de almacenamiento y más.
• Composable con otros servidores MCP: Apila Playwright junto a GitHub, tu base de datos o tu servidor MCP de monitoreo y Claude Code puede mover trabajo de extremo a extremo en todos ellos.
• Estándar abierto: MCP es portable. El mismo servidor de Playwright funciona en Cursor, VS Code, Windsurf y Claude Desktop si cambias de cliente.

Agrega el servidor, ejecuta /mcp para confirmar, y tu próxima indicación “ve a probar la página de inicio de sesión” se convierte en una sesión de navegador real — impulsada por Claude Code, observada (o no) en modo con interfaz gráfica, y verificable a través de snapshots de accesibilidad.