Guía práctica de Playwright MCP: deja que Claude, Codex y Cursor controlen el navegador

Añades [mcp_servers.playwright] en .codex/config.toml, ejecutas codex y el navegador se abre de verdad. Aun así, la IA no llama a las herramientas de navegador; o abre la página, pero no encuentra el botón de la barra de navegación. Esta guía cubre la configuración completa para Claude Code, Codex y Cursor, la checklist de primera validación y los permisos de navegador que no conviene entregar a una IA sin cuidado.

---

Qué es Playwright MCP

Playwright MCP es el MCP server mantenido oficialmente por Microsoft que expone la automatización de navegador de Playwright a herramientas de programación con IA mediante Model Context Protocol. Su principio central no es reconocer capturas. Opera sobre el accessibility tree y le da a la IA una vista estructurada de la página para encontrar botones, enlaces, campos de entrada y otros elementos interactivos.

Capacidades principales y lista de herramientas

Playwright MCP cubre los escenarios principales de automatización de navegador:

• Navegación: abrir URL, avanzar, retroceder, recargar
• Clic y entrada: hacer clic en elementos, llenar formularios, usar el teclado
• Capturas y snapshots: tomar capturas de pantalla y obtener accessibility snapshots
• Diálogos y pestañas: manejar alert/confirm/prompt y gestionar varias pestañas
• Red y console: interceptar solicitudes de red y capturar console logs
• Estado de almacenamiento: guardar y restaurar cookies, localStorage y sessionStorage

Con eso puede manejar desde un clic simple hasta el envío de formularios complejos.

Diferencia con Playwright CLI/SKILLS

El README oficial de Microsoft deja clara la elección entre dos rutas:

• Ruta MCP: adecuada cuando necesitas estado persistente, introspección rica y un contexto de navegador continuo, por ejemplo automatización exploratoria, pruebas auto-reparables o tareas largas. La desventaja es que el tool schema y el accessibility tree entran en el contexto y consumen tokens.
• Ruta CLI + SKILLS: adecuada para flujos de código de alto rendimiento, con menor consumo de contexto, pero requiere llamar a Playwright mediante comandos o scripts.

Si ya usas una herramienta de programación con IA compatible con MCP, como Claude Code, Codex o Cursor, Playwright MCP es la forma más directa de incorporar herramientas de navegador al flujo existente.

Diferencia con Browser Use

Browser Use es un agent loop en Python. Escribes código Python contra su API y el agent decide las acciones de navegador a partir de un prompt. Playwright MCP es distinto: no proporciona el agent loop. Proporciona la capa de herramientas de navegador, y tu MCP client existente, Claude Code, Codex o Cursor, decide cuándo invocarlas.

Si eres desarrollador Python y quieres arrancar rápido con Browser Agent, puedes empezar por el tutorial de Browser Use para abrir páginas, hacer clic en botones y extraer información. Si ya trabajas dentro de un MCP client y quieres añadir capacidad de navegador a esa herramienta, esta guía te ayuda a instalar, validar y asegurar Playwright MCP.

No sustituye al framework de pruebas

Playwright MCP no sustituye al framework de pruebas de Playwright. Es útil para automatización exploratoria y validación frontend, pero una suite E2E estable todavía debe escribirse con scripts de prueba Playwright. Las pruebas necesitan determinismo, repetibilidad y mantenibilidad; las acciones de navegador guiadas por IA no son totalmente controlables. Si te interesa el testing en modo navegador, también puedes leer Vitest Browser Mode.

---

Configurar Playwright MCP en Claude Code

Requisitos previos

Claude Code necesita Node.js 18+ para ejecutar Playwright MCP. Comprueba tu versión de Node:

node --version

Si es inferior a 18, actualiza Node.js primero.

Comando para añadirlo

Claude Code ofrece un comando específico para gestionar MCP. Ejecútalo en la raíz del proyecto:

claude mcp add playwright npx @playwright/mcp@latest

Este comando registra el Playwright MCP server en Claude Code. Usa @playwright/mcp@latest; no copies nombres antiguos de paquetes comunitarios como @executeautomation/playwright-mcp-server.

Configuración de proyecto .mcp.json

Si quieres compartir la configuración de Playwright MCP con el equipo, puedes crear .mcp.json en la raíz del proyecto:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "BROWSER_PATH": "/usr/bin/chromium"
      }
    }
  }
}

Cuando Claude Code detecta un .mcp.json de proyecto, pide aprobación. Es una medida de seguridad para evitar que el proyecto introduzca un MCP server no confiable sin aviso.

Expansión de variables de entorno

.mcp.json admite expansión de variables de entorno para rutas propias de cada máquina y valores sensibles:

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

Tool Search y gestión de tokens de salida

Claude Code activa MCP Tool Search por defecto, lo que carga herramientas de forma diferida y reduce consumo de contexto. Cuando la salida MCP es grande, Claude Code también gestiona tokens, con un máximo de salida por defecto de 25.000 tokens. Si la IA no usa herramientas de navegador, comprueba:

1. Que el MCP server arrancó correctamente en los logs de Claude Code
2. Que Tool Search está habilitado, lo cual ocurre por defecto en Claude Code
3. Que Node.js es versión 18 o superior

---

Configurar Playwright MCP en Codex

OpenAI Codex soporta MCP servers tanto en la CLI como en la IDE extension, pero su configuración no es igual a la de Claude Code.

Comando para añadirlo

La CLI de Codex incluye un comando de gestión MCP:

codex mcp add playwright -- npx @playwright/mcp@latest

En Codex, -- separa el nombre del server del comando real.

Ubicación del archivo de configuración

La configuración MCP de Codex se guarda en config.toml. Hay dos ubicaciones:

• Nivel de usuario: ~/.codex/config.toml, con efecto global
• Nivel de proyecto: .codex/config.toml en la raíz del proyecto, solo para ese proyecto

La CLI y la IDE extension comparten la configuración.

Fragmento de config.toml

Para configurar manualmente, añade esto en config.toml:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

Si necesitas pasar variables de entorno o ajustar aprobación de herramientas, añade:

env_vars = ["HOME", "STORAGE_STATE_PATH"]
approval_mode = "prompt"

Modos de aprobación de herramientas

Codex proporciona tres modos de aprobación:

• approval_mode = "allow": ejecutar automáticamente todas las llamadas a herramientas
• approval_mode = "prompt": pedir confirmación al usuario antes de cada llamada
• approval_mode = "deny": rechazar todas las llamadas a herramientas

Para herramientas de alto riesgo de Playwright MCP, como browser_run_code_unsafe, conviene usar:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
disabled_tools = ["browser_run_code_unsafe"]
approval_mode = "prompt"

Así evitas que herramientas de alto riesgo se ejecuten automáticamente y mantienes las acciones sensibles detrás de aprobación humana.

Soporte para HTTP server

Codex soporta dos tipos de MCP server:

• STDIO server: comunicación con un proceso local, útil para herramientas que necesitan acceso al sistema local, como Playwright MCP
• HTTP server: soporta bearer token y autenticación OAuth

Playwright MCP usa STDIO, así que no necesitas configurar HTTP para el flujo estándar.

---

Configurar Playwright MCP en Cursor

Cursor configura MCP desde Settings UI, a diferencia de los flujos de línea de comandos de Claude Code y Codex.

Pasos en la UI

Según la documentación oficial de Playwright, la configuración en Cursor es:

1. Abre Cursor Settings (Cmd+, o desde el menú Settings)
2. Ve a la página de ajustes MCP (Settings -> MCP)
3. Haz clic en “Add new MCP Server”
4. Completa la configuración:
   • Server name: playwright
   • Command type: npx
   • Command: @playwright/mcp@latest

Parámetros estándar

La configuración de MCP server en Cursor admite los parámetros estándar de Playwright MCP:

• --headless: modo sin ventana de navegador visible; durante desarrollo, headed facilita la observación
• --browser: elegir navegador (chrome/firefox/webkit/msedge)
• --output-dir: ruta del directorio de salida
• --storage-state: ruta del archivo de estado de sesión

La lista completa aparece en la tabla de parámetros estándar más abajo.

Referencia de configuración

La documentación MCP de Cursor está en la documentación oficial de Cursor. Para detalles de Playwright MCP, usa la documentación oficial de Playwright y el README de Microsoft como referencia, y asegúrate de usar el paquete oficial @playwright/mcp@latest.

---

Tabla de parámetros de configuración estándar

Playwright MCP ofrece varios parámetros para controlar comportamiento del navegador, límites de seguridad y gestión de salidas.

Parámetro	Función	Valor predeterminado	Nota de seguridad
--headless	Modo sin mostrar ventana de navegador	false (headed)	En desarrollo conviene headed para observar la operación del navegador
--browser	Elegir tipo de navegador	chrome	Opciones: chrome, firefox, webkit, msedge
--allowed-origins	Lista de orígenes permitidos	Sin límite	No es un límite de seguridad; no afecta redirects y no evita por sí solo el acceso a sitios sensibles
--blocked-origins	Lista de orígenes bloqueados	Ninguno	No es un límite de seguridad, misma advertencia
--isolated	Modo aislado, cada sesión usa un profile independiente	false	Recomendado para clientes concurrentes o varios proyectos
--storage-state	Ruta de un archivo de estado de sesión	Ninguno	Guarda cookies y localStorage; cuidado con cuentas reales
--output-dir	Directorio de salida para capturas, logs, etc.	Ninguno	Define una ruta para encontrar fácilmente los resultados
--save-session	Guardar estado de sesión	false	Úsalo junto con persistent profile
--snapshot-mode	Modo de accessibility snapshot	default	Controla el nivel de detalle del snapshot
--allow-unrestricted-file-access	Permitir acceso sin restricción a archivos	false	Alto riesgo, actívalo con prudencia
--secrets	Configuración de secretos por variables de entorno o archivos	Ninguno	Para gestionar información sensible

Recordatorio clave: la documentación oficial indica que --allowed-origins y --blocked-origins no son límites de seguridad y no afectan redirects. Si necesitas restringir los sitios que puede visitar la IA, no dependas solo de esos parámetros.

---

Comparativa de tres modos de profile

Playwright MCP soporta tres modos de profile que afectan persistencia de sesión, concurrencia y límites de seguridad.

Modo	Guardado de sesión	Ruta de profile	Concurrencia	Caso de uso	Recomendación de seguridad
persistent	Guarda cookies, localStorage, etc.	macOS: ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}	Un profile solo puede usarse por una browser instance a la vez	Tareas largas donde la IA debe recordar la sesión	No uses cuentas reales; empieza con una cuenta de prueba
isolated	No guarda; cada sesión es independiente	Directorio temporal, limpiado por sesión	Soporta clientes concurrentes o varios proyectos	Pruebas, exploración, tareas sin estado de sesión	Recomendado como primera opción en producción
browser extension	Guarda según el navegador	Directorio de extensión del navegador	Depende del navegador	Conectarse a una sesión de navegador existente	Uso avanzado; entiende primero el modelo de seguridad de extensiones

Limitación de persistent profile

Un persistent profile solo puede ser usado por una browser instance a la vez. Si necesitas varios clients o varios proyectos usando Playwright MCP en paralelo, debes:

• Usar modo --isolated
• O configurar un --user-data-dir distinto para cada client

Ejemplo de ruta persistent profile en macOS:

~/Library/Caches/ms-playwright/mcp-chrome-a1b2c3d4

La parte {workspace-hash} se genera automáticamente según el proyecto, así que proyectos distintos usan profiles distintos.

Estado de sesión y límites de seguridad

persistent profile guarda cookies, localStorage y sessionStorage. La IA puede acceder al estado de sesión guardado en el navegador. Si usas una cuenta real, podría acceder a datos personales, información de pago y ajustes de cuenta.

Prácticas recomendadas:

• En producción, usa --isolated para no guardar estado de sesión
• Cuando la IA necesite operar con sesión, usa una cuenta de prueba, no una cuenta real
• No dejes que la IA inicie sesión automáticamente en tu cuenta real ni visite páginas de pago

La gestión de sesiones se tratará con más detalle en un artículo posterior sobre estado de sesión de navegadores IA. Aquí solo fijamos el límite.

---

Advertencia de seguridad sobre browser_run_code_unsafe

Advertencia de seguridad: browser_run_code_unsafe permite ejecutar scripts Playwright arbitrarios. La documentación oficial lo marca como RCE-equivalent. Actívalo solo para MCP clients totalmente confiables. En producción, desactívalo o exige aprobación humana con approval_mode: prompt en Codex.

Playwright MCP incluye una herramienta de alto riesgo llamada browser_run_code_unsafe. Puede ejecutar cualquier script Playwright dentro del contexto del navegador. El peligro está claro:

• Si el MCP client se ve comprometido o la conducta de la IA no está controlada, un atacante puede usar esta herramienta para ejecutar código arbitrario
• La IA puede leer todos los datos del navegador, incluidos cookies, localStorage, sessionStorage y datos personales de cuentas conectadas
• Si el navegador está en una página de pago o de ajustes de cuenta, la IA puede leer y filtrar datos sensibles

Recomendaciones de configuración segura

Entorno de producción:

1. Desactivar browser_run_code_unsafe:

   Añade esto en ~/.codex/config.toml de Codex:

   [mcp_servers.playwright]
   command = "npx"
   args = ["@playwright/mcp@latest"]
   disabled_tools = ["browser_run_code_unsafe"]

2. O configurar modo de aprobación:

   [mcp_servers.playwright]
   command = "npx"
   args = ["@playwright/mcp@latest"]
   approval_mode = "prompt"

   Así Codex mostrará una confirmación antes de cada llamada a browser_run_code_unsafe, y tendrás que aprobarla manualmente.

Entorno de desarrollo:

Si de verdad necesitas usar browser_run_code_unsafe:

• Actívalo solo en desarrollo local, no en producción ni con cuentas reales
• Asegúrate de entender por completo el script que se va a ejecutar
• No dejes que la IA genere y ejecute scripts automáticamente; escribe tú el script y pide a la IA que ejecute ese script conocido

No recomendado para principiantes

Si acabas de empezar con Playwright MCP, no uses browser_run_code_unsafe. Prioriza herramientas más seguras de Playwright MCP, como browser_click, browser_navigate y browser_screenshot. Tienen límites claros y no ejecutan código arbitrario.

---

Checklist de seguridad para MCP Tools

MCP permite que la IA llame herramientas externas, pero “conectar MCP” no equivale a “dejar que la IA haga cualquier cosa”. Hay que controlar límites de seguridad tanto del lado del cliente como del lado del servidor.

Recomendaciones de seguridad del lado del cliente

1. Pedir confirmación en acciones sensibles: antes de llamar browser_run_code_unsafe, visitar páginas de pago, modificar ajustes de cuenta o borrar datos, pide confirmación al usuario. No dejes que la IA ejecute automáticamente estas operaciones de alto riesgo.

2. Mostrar tool inputs antes de ejecutar: deja que el usuario vea los parámetros concretos que la IA va a usar. Por ejemplo, si la IA quiere hacer clic en un botón, muestra el selector o las coordenadas y confirma que son correctos.

3. Evitar fugas maliciosas de datos: revisa la salida de herramientas para evitar que información sensible, como contraseñas, tokens o datos personales, sea leída por la IA y enviada fuera. Si una herramienta devuelve datos sensibles, no dejes que la IA los escriba en logs ni los envíe a servidores externos.

4. Configurar timeout: las operaciones del navegador pueden quedarse atascadas, consumir recursos o bloquear otras tareas. Define un timeout razonable para cada llamada, por ejemplo 30 segundos, y cancela automáticamente al superarlo.

5. Registrar tool usage: conserva logs de operación para auditoría y diagnóstico. Incluye nombre de herramienta, hora, parámetros de entrada, resultado y registro de aprobación del usuario.

6. Verificar tool results: comprueba que capturas, console logs y solicitudes de red coinciden con lo esperado. Si la IA informa “clic exitoso” pero la captura muestra que nada cambió, hay que investigar.

Recomendaciones de seguridad del lado del servidor

Si desarrollas tu propio MCP server (Playwright MCP ya es el server oficial, no necesitas desarrollarlo), sigue estas recomendaciones:

1. Validar entradas: valida URL, selectores y contenido de entrada para evitar ataques de inyección. No permitas que la IA pase una URL maliciosa o un XSS payload sin validar.

2. Controlar acceso: limita los dominios, rutas de archivo y capacidades de navegador accesibles. Por ejemplo, bloquea IP internas o rutas sensibles.

3. Aplicar límites de frecuencia: evita que la IA llame herramientas con tanta frecuencia que agote recursos o cause bloqueo del sitio objetivo. Define un límite razonable, como máximo 10 llamadas por minuto.

4. Sanear salidas: elimina información sensible antes de devolver datos a la IA. Por ejemplo, no devuelvas cadenas completas de cookies si basta con una parte necesaria.

---

Primera tarea de validación y checklist de aceptación

Tras la configuración, usa una tarea simple para comprobar que Playwright MCP está conectado correctamente.

Ejemplo de tarea

Pide a la IA que abra la preview local http://localhost:4321, haga clic en el menú de navegación, tome una captura y reporte console errors.

Paso a paso:

1. Asegúrate de que Playwright MCP está añadido a tu cliente, ya sea Claude Code, Codex o Cursor

2. Arranca el servidor de desarrollo local, como Astro o Next.js, y confirma que http://localhost:4321 es accesible

3. Introduce este prompt en Claude Code/Codex/Cursor:

   Abre http://localhost:4321, haz clic en "Artículos" en el menú de navegación, toma una captura y reporta si la página tiene console errors.

4. Observa si la IA llama a las herramientas de navegador, si el navegador arranca y si la página se abre

Checklist de aceptación

Comprobación	Resultado esperado	Cómo confirmarlo
El navegador arranca	En headed mode se abre una ventana, o en headless arranca el proceso	Observar la UI o el administrador de procesos
El MCP server está conectado	Los logs del cliente muestran “Connected to MCP server”	Revisar logs del cliente
Devuelve accessibility snapshot	La IA encuentra el menú de navegación y puede hacer clic	La salida de la IA incluye una descripción del clic
La llamada de herramienta requiere aprobación	Depende de la configuración; Codex puede mostrar un diálogo de aprobación	Observar si el cliente pide confirmación
Salidas y logs son trazables	Capturas, console logs y demás salidas aparecen en --output-dir	Revisar el directorio configurado

Diagnóstico de fallos

La IA no llama herramientas de navegador:

• Revisa los logs del cliente y confirma que el MCP server se añadió correctamente
• Comprueba que el cliente soporta MCP Tool Search; Claude Code lo activa por defecto
• Verifica que Node.js es versión 18 o superior

El navegador se abre pero no encuentra el botón:

• Playwright MCP opera sobre el accessibility tree, no sobre capturas. Si la página carece de etiquetas semánticas o atributos ARIA, la IA puede no reconocer el elemento
• Revisa la estructura HTML y asegúrate de que el botón tiene una etiqueta accesible o role
• O ajusta el parámetro --snapshot-mode para cambiar el nivel de detalle del snapshot

El navegador arranca pero se cierra enseguida:

• Puede ser modo headless o que el script haya terminado
• Revisa los logs del cliente y confirma si el navegador arrancó y cerró normalmente
• Si usas headed mode, la ventana debería quedarse abierta hasta que la IA informe que terminó

---

Cuándo elegir Playwright MCP frente a CLI/SKILLS

El README oficial de Microsoft señala que, para coding agents en flujos de código de alto rendimiento, CLI + SKILLS puede ser más adecuado, porque MCP introduce tool schemas y el accessibility tree en el contexto y consume tokens. MCP encaja mejor cuando necesitas estado persistente, introspección rica y un contexto de navegador continuo para automatización exploratoria, pruebas auto-reparables o tareas largas.

Tabla comparativa por escenario

Escenario	Recomendar Playwright MCP	Recomendar Playwright CLI + SKILLS
Automatización exploratoria, pruebas auto-reparables	Sí, encaja	No, no encaja
Tareas largas con contexto de navegador persistente	Sí, encaja	No, no encaja
Flujos de código de alto rendimiento	No, consume más contexto	Sí, encaja
Necesidad de mínimo consumo de contexto	No, no encaja	Sí, encaja
Ya usas un MCP client como Claude Code/Codex/Cursor	Sí, encaja	No, no encaja

Este artículo no entra en el uso concreto de SKILLS. Un artículo posterior cubrirá la validación de navegador con Codex en la práctica.

---

Resumen y siguientes pasos

Esta guía cubrió la configuración de Playwright MCP en Claude Code, Codex y Cursor, la checklist de primera validación y los límites de seguridad: el riesgo RCE de browser_run_code_unsafe, la persistencia de sesión en modos de profile y el hecho de que --allowed-origins no es un límite de seguridad.

Resumen de diferencias de configuración

• Claude Code: usar claude mcp add o .mcp.json a nivel de proyecto; Tool Search está activo por defecto
• Codex: usar codex mcp add o config.toml; approval_mode controla herramientas de alto riesgo
• Cursor: configurar desde Settings UI, con un flujo distinto a los dos anteriores

Siguientes pasos recomendados

• Necesitas comparar herramientas: lee Browser Use vs Stagehand vs Playwright MCP, guía 2026 de selección de herramientas de navegador IA
• Necesitas gestionar sesión: lee Gestión del estado de sesión en navegadores IA
• Necesitas pruebas frontend: lee Pruebas y validación frontend con Playwright
• Necesitas validación de navegador con Codex: lee Validación de navegador con Codex en la práctica
• Necesitas infraestructura gestionada: lee Infraestructura de navegadores gestionados
• Necesitas seguridad y approvals: lee Seguridad de navegadores IA y diseño de aprobaciones

Si acabas de configurar Playwright MCP, ejecuta primero la tarea de validación en localhost:4321. Confirma que el navegador arranca, que la IA llama herramientas y que las capturas se escriben en el directorio configurado. Si algo falla, sigue la FAQ y revisa la versión de Node.js, los logs del cliente y el estado de conexión del MCP server.