Playwright MCP
Servidor MCP de Microsoft para que un agente de IA controle un navegador con Playwright mediante instantáneas de accesibilidad. Licencia Apache-2.0.
Fuente: Playwright MCP (repositorio oficial) · Oficial · Mantiene Microsoft · Licencia Apache-2.0 · Ver original en github.com
Ficha técnica
- Organización
- Microsoft (se abre en una pestaña nueva)
- Transporte
- Proceso local lanzado por el cliente con npx, o HTTP con --port
- Clientes compatibles
- VS Code
- Cursor
- Windsurf
- Claude Desktop
- Claude Code
- Cline
- Codex
- Gemini CLI
- Goose
- Grok
- Junie
- Warp
- Instalación
npx @playwright/mcp@latest
Qué es y qué expone
Playwright MCP es un servidor MCP (Model Context Protocol) que ofrece capacidades de automatización de navegador con Playwright. Según su README, permite que los LLM interactúen con páginas web mediante instantáneas de accesibilidad estructuradas, sin necesidad de capturas de pantalla ni de modelos con visión.
El README resume sus rasgos en tres puntos. Es rápido y ligero: usa el árbol de accesibilidad de Playwright y no entrada basada en píxeles. Es apto para LLM: no necesita modelos de visión y opera solo con datos estructurados. Y aplica las herramientas de forma determinista, lo que evita la ambigüedad habitual de los enfoques basados en capturas de pantalla.
En su package.json, el paquete @playwright/mcp declara como autor a Microsoft Corporation y la licencia Apache-2.0; el archivo LICENSE contiene la licencia Apache, versión 2.0, de enero de 2004. Funciona con VS Code, Cursor, Windsurf, Claude Desktop, Goose, Grok, Junie o cualquier otro cliente MCP.
Valoración de KIRELEN: encaja con automatizaciones de navegador exploratorias y con pruebas guiadas por un agente, en las que este necesita razonar sobre la estructura de la página y no solo repetir un guion.
Qué problema resuelve
Para manejar un navegador, un agente necesita saber qué hay en la página. Playwright MCP lo resuelve con instantáneas de accesibilidad estructuradas, de modo que no hacen falta capturas de pantalla ni modelos con visión.
El propio README plantea cuándo conviene este servidor y cuándo no. Este paquete ofrece la interfaz MCP de Playwright; si se usa un agente de programación, el README sugiere valorar CLI+SKILLS. Según el README, los agentes de programación modernos favorecen cada vez más los flujos basados en CLI expuestos como skills porque son más eficientes en tokens: evitan cargar esquemas de herramientas grandes y árboles de accesibilidad extensos en el contexto del modelo.
MCP sigue siendo relevante, dice el README, para bucles de agente especializados que se benefician de estado persistente, introspección rica y razonamiento iterativo sobre la estructura de la página, como la automatización exploratoria, las pruebas que se reparan solas o los flujos autónomos de larga duración.
Valoración de KIRELEN: para un agente de programación que ya trabaja en la terminal, conviene valorar primero CLI+SKILLS, que el propio README presenta como más eficiente en tokens, y reservar este servidor para los casos en los que mantener el contexto del navegador compense el coste.
Cómo funciona
Playwright MCP expone al cliente MCP las acciones de un navegador controlado con Playwright. La configuración estándar arranca el servidor con npx y el paquete @playwright/mcp@latest, y funciona en la mayoría de las herramientas.
Instantáneas de accesibilidad
browser_snapshot captura una instantánea de accesibilidad de la página actual y, según el README, es mejor que una captura de pantalla. Su parámetro target es la referencia exacta del elemento en la instantánea de la página o un selector único, y es lo que usan las acciones para saber sobre qué elemento actuar. browser_take_screenshot toma una captura de pantalla, pero no se pueden hacer acciones a partir de ella: para actuar hay que usar browser_snapshot. browser_find busca texto o una expresión regular en la instantánea de la página actual y devuelve los nodos coincidentes con algunas líneas de contexto.
Perfiles del navegador
Se puede ejecutar con un perfil persistente, como un navegador normal (por defecto), en contextos aislados para sesiones de prueba, o conectarse al navegador existente mediante la extensión. En el perfil persistente se guarda toda la información de sesión, y se puede borrar entre sesiones para limpiar el estado; depende del directorio de trabajo del cliente MCP, de modo que proyectos distintos obtienen perfiles distintos automáticamente. Un perfil persistente solo puede usarse en una instancia de navegador a la vez, así que varios clientes MCP que compartan el mismo espacio de trabajo entran en conflicto: para ejecutarlos en paralelo hay que usar --isolated o un --user-data-dir distinto.
En el modo aislado (--isolated), el perfil se mantiene en memoria y no se guarda en disco: cada sesión empieza en un perfil aislado y, cuando se pide cerrar el navegador, la sesión se cierra y se pierde todo el estado de almacenamiento. Con --storage-state se parte de un archivo de estado de almacenamiento. La extensión de Chrome de Playwright MCP permite conectarse a pestañas existentes del navegador y aprovechar las sesiones con inicio de sesión y el estado del navegador; --extension conecta con una instancia en ejecución (solo Edge o Chrome) y requiere tener instalada la extensión de Playwright.
Ejecución y transporte
Por defecto el navegador se ejecuta con interfaz; --headless lo ejecuta sin ella, y --browser elige el navegador o el canal de Chrome: chrome, firefox, webkit o msedge. Con --idle-timeout se cierra el navegador tras un tiempo sin llamadas completadas y la siguiente llamada lo relanza; por defecto es una hora en navegadores sin interfaz y nunca en los que la tienen. Con un navegador con interfaz en un sistema sin pantalla o desde procesos de trabajo de un IDE, hay que ejecutar el servidor desde un entorno con DISPLAY y pasar --port para activar el transporte HTTP. El indicador --port define el puerto en el que escuchar para el transporte SSE, y el servidor se enlaza por defecto a localhost: --host con 0.0.0.0 lo enlaza a todas las interfaces.
Capacidades opcionales
El indicador --caps activa capacidades adicionales; la tabla de opciones del README nombra vision, pdf y devtools, y los títulos de los grupos de herramientas añaden config, network, storage y testing. Hay grupos opcionales de herramientas de configuración (--caps=config), de red (--caps=network), de almacenamiento (--caps=storage), de DevTools (--caps=devtools), basadas en coordenadas (--caps=vision), de generación de PDF (--caps=pdf) y de aserciones de prueba (--caps=testing).
Del cliente MCP al navegador
Leer el diagrama como texto
- Capa 1
- Cliente MCP
- Capa 2
- Playwright MCP
- Capa 3
- Playwright
- Capa 4
- Navegador
Conexiones
- Cliente MCP → Playwright MCP
- Playwright MCP → Playwright
- Playwright → Navegador
Cómo actúa el agente sobre una página
Leer el diagrama como texto
- Snapshot de accesibilidad
- Referencia del elemento
- Acciones en la página
Conexiones
- Snapshot de accesibilidad → Referencia del elemento
- Referencia del elemento → Acciones en la página
Tecnologías utilizadas
| Tecnología | Para qué |
|---|---|
| TypeScript | Lenguaje del repositorio, según GitHub |
| JavaScript | Lenguaje del repositorio, según GitHub |
| Playwright | Automatiza el navegador que controla el servidor |
| Node.js | Ejecuta el servidor con npx |
| Chrome, Firefox, WebKit y Edge | Navegadores que se eligen con --browser |
| Docker | Imagen del servidor, que solo admite Chromium sin interfaz por ahora |
Cómo empezar: requisitos e instalación
- Comprueba los requisitos. La guía de inicio de la documentación pide Node.js 20 o posterior; el README aún indica Node.js 18 o posterior, así que con la 20 cumples los dos. Necesitas además un cliente MCP: VS Code, Cursor, Windsurf, Claude Desktop, Goose, Grok, Junie o cualquier otro.
- Añade el servidor a tu cliente. La configuración estándar está en «Configuración». En VS Code, tras instalarlo, el servidor queda disponible para el agente de GitHub Copilot. Con Claude Code, el README lo añade con la CLI:
claude mcp add playwright npx @playwright/mcp@latest- Elige el navegador. Con
--browserse elige chrome, firefox, webkit o msedge. Para conectar con un navegador en ejecución (solo Edge o Chrome),--extensionrequiere la extensión de Playwright instalada; con Docker, solo hay Chromium sin interfaz por ahora. - Activa lo que necesites.
--capsañade capacidades opcionales a las herramientas básicas.
Estado del proyecto y licencia
Playwright MCP es de Microsoft: su package.json declara como autor a Microsoft Corporation y la licencia Apache-2.0, y el archivo LICENSE contiene la licencia Apache, versión 2.0, de enero de 2004.
Según la ficha del repositorio en GitHub, comprobada el 2026-10-20, el último release publicado es v0.0.83, del 2026-09-28, la misma versión que declara el package.json; el último push es del 2026-10-19. Es un proyecto activo, con releases.
Herramientas expuestas
| Herramienta | Qué hace |
|---|---|
browser_ | Abre una URL. |
browser_ | Vuelve a la página anterior del historial. |
browser_ | Captura una instantánea de accesibilidad de la página actual. |
browser_ | Toma una captura de pantalla; no sirve para actuar. |
browser_ | Hace clic en una página web. |
browser_ | Escribe texto en un elemento editable. |
browser_ | Rellena varios campos de un formulario. |
browser_ | Selecciona una opción de una lista desplegable. |
browser_ | Pasa el ratón sobre un elemento. |
browser_ | Pulsa una tecla del teclado. |
browser_ | Espera a que un texto aparezca o desaparezca, o a que pase un tiempo. |
browser_ | Evalúa una expresión JavaScript en la página o en un elemento. |
browser_ | Lista, crea, cierra o selecciona una pestaña. |
browser_ | Devuelve todos los mensajes de la consola. |
browser_ | Devuelve la lista numerada de peticiones de red desde que se cargó la página. |
browser_ | Sube uno o varios archivos. |
browser_ | Gestiona un cuadro de diálogo. |
browser_ | Cierra la página. |
browser_ | Simula peticiones de red que coinciden con un patrón de URL. Opcional: --caps=network. |
browser_ | Guarda cookies y local storage en un archivo para reutilizarlos. Opcional: --caps=storage. |
browser_ | Inicia la grabación de una traza. Opcional: --caps=devtools. |
browser_ | Hace clic con el ratón en una posición dada. Opcional: --caps=vision. |
browser_ | Guarda la página como PDF. Opcional: --caps=pdf. |
browser_ | Genera un localizador del elemento para usarlo en pruebas. Opcional: --caps=testing. |
browser_ | Verifica que un texto es visible en la página. Opcional: --caps=testing. |
Configuración
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}Ejemplo de uso
Una petición realista
Ejemplo de KIRELEN (no oficial): le pides al agente que abra la página de contacto de tu sitio, compruebe que el formulario funciona y lo rellene con datos de prueba. El agente puede usar browser_navigate para abrir la URL, browser_snapshot para obtener la instantánea con las referencias de los elementos, browser_fill_form para rellenar varios campos y browser_click para enviar el formulario. Después, browser_take_screenshot deja una captura como evidencia y browser_console_messages devuelve los mensajes de la consola si algo falla.
Sesiones y estado inicial
Si la página exige iniciar sesión, el modo aislado con un estado de almacenamiento guardado evita arrastrar sesiones personales. El README da esta configuración, con --isolated y --storage-state:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--isolated",
"--storage-state={path/to/storage.json}"
]
}
}
}Para preparar el estado inicial hay varias vías. Con --user-data-dir se parte de un directorio de datos de usuario, que conserva todos los datos del navegador entre sesiones; con --storage-state, de un archivo de estado de almacenamiento, que carga cookies y local storage en un contexto de navegador aislado. Para el estado de la página, --init-page apunta a un archivo TypeScript que se evalúa sobre el objeto página de Playwright, lo que permite ejecutar código arbitrario para preparar la página. Este es el ejemplo del README:
// init-page.ts
export default async ({ page }) => {
await page.context().grantPermissions(['geolocation']);
await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
await page.setViewportSize({ width: 1280, height: 720 });
};Otras opciones de ajuste: con --device se emula un dispositivo, por ejemplo iPhone 15, y con --mobile un dispositivo móvil genérico (Pixel 10 en Chromium, iPhone 17 en WebKit); las páginas móviles suelen ser más ligeras, lo que ahorra tokens. Con --init-script se añade un archivo JavaScript que se evalúa en cada página antes que los scripts de la propia página. El tiempo de espera de las acciones es de 5000 ms por defecto (--timeout-action) y el de las navegaciones, de 60000 ms (--timeout-navigation). El servidor también puede configurarse con un archivo de configuración JSON indicado con la opción --config.
Ejecución sin pantalla y con Docker
Si el navegador con interfaz debe ejecutarse en un sistema sin pantalla, o desde los procesos de trabajo de un IDE, el servidor se ejecuta desde un entorno con DISPLAY y se pasa --port para activar el transporte HTTP:
npx @playwright/mcp@latest --port 8931En la configuración del cliente se indica entonces la URL del endpoint HTTP:
{
"mcpServers": {
"playwright": {
"url": "http://localhost:8931/mcp"
}
}
}La imagen de Docker solo admite Chromium sin interfaz por ahora. El README la configura así:
{
"mcpServers": {
"playwright": {
"command": "docker",
"args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
}
}
}Como servicio de larga duración en Docker, el servidor escucha en el puerto 8931 del host y puede usarlo cualquier cliente MCP. También se puede usar por código: createConnection crea una conexión con el navegador configurado para ejecutarse sin interfaz (headless).
El ejemplo de la documentación
La introducción de playwright.dev muestra el ciclo completo con una lista de tareas de demostración. El LLM lee la instantánea de accesibilidad, encuentra referencias de elementos como e5 y las pasa como destino de la siguiente llamada: el agente escribe «Buy groceries» en el cuadro de texto con browser_type, usando su referencia e5, y lo envía. Con esas referencias hace clic en botones, rellena formularios y marca casillas, sin capturas de pantalla ni coordenadas que adivinar. Es lo que muestra la captura de abajo.
Seguridad y límites
Playwright MCP no es un límite de seguridad, y el README remite a las buenas prácticas de seguridad de MCP. Las listas de orígenes permitidos y bloqueados (--allowed-origins y --blocked-origins) tampoco sirven como límite de seguridad y no afectan a las redirecciones.
Por defecto, el acceso al sistema de archivos se restringe a los directorios raíz del espacio de trabajo (o al directorio actual si no hay raíces) y se bloquea la navegación a URL file://; --allow-unrestricted-file-access lo levanta. La herramienta browser_run_code_unsafe ejecuta JavaScript arbitrario en el proceso del servidor de Playwright y equivale a ejecución remota de código (RCE). Además, con la API experimental WebMCP las páginas pueden registrar sus propias herramientas para el agente; según la documentación, sus nombres, descripciones, esquemas y resultados los da la página, así que hay que tratarlos como entrada no confiable.
El perfil persistente guarda toda la información de sesión, y la extensión permite aprovechar las sesiones con inicio de sesión de tu navegador: un agente que navega por páginas que no controlas trabaja con ese estado. Para limitarlo, el modo aislado mantiene el perfil en memoria. El servidor comprueba por defecto el host al que está enlazado y pasar * a --allowed-hosts desactiva esa comprobación; con --secrets se indica un archivo con secretos en formato dotenv.
Valoración de KIRELEN: como Playwright MCP no es un límite de seguridad, conviene ejecutarlo con perfil aislado, con el acceso a archivos restringido y sin sesiones personales abiertas, sobre todo cuando el agente navega por páginas que no controlas.
Enlaces oficiales
Fuentes consultadas
Repositorio
- microsoft/playwright-mcp (README) · Microsoft
- microsoft/playwright-mcp (LICENSE) · Microsoft
- @playwright/mcp (package.json) · Microsoft