Servidor MCP de Playwright | Awesome MCP Servers

Playwright MCP

Un servidor de Model Context Protocol (MCP) que proporciona capacidades de automatización de navegador utilizando Playwright. Este servidor permite que los LLM interactúen con páginas web mediante instantáneas estructuradas de accesibilidad, evitando la necesidad de capturas de pantalla o modelos ajustados visualmente.

Características clave

Rápido y ligero: Utiliza el árbol de accesibilidad de Playwright, no entrada basada en píxeles.
Amigable con LLM: No se necesitan modelos de visión, opera puramente con datos estructurados.
Aplicación determinista de herramientas: Evita la ambigüedad común con los enfoques basados en capturas de pantalla.

Casos de uso

Navegación web y relleno de formularios
Extracción de datos de contenido estructurado
Pruebas automatizadas impulsadas por LLM
Interacción general del navegador para agentes

Configuración de ejemplo

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

Instalación en VS Code

Puede instalar el servidor Playwright MCP usando la CLI de VS Code:

# For VS Code
code --add-mcp '{"name":"playwright","command":"npx","args":["@hyhfish/mcp-hyh@latest"]}'

Después de la instalación, el servidor Playwright MCP estará disponible para usarse con su agente GitHub Copilot en VS Code.

Línea de comandos

El servidor Playwright MCP admite las siguientes opciones de línea de comandos:

--browser <browser>: Canal de navegador o Chrome a utilizar. Valores posibles:
- chrome, firefox, webkit, msedge
- Canales de Chrome: chrome-beta, chrome-canary, chrome-dev
- Canales de Edge: msedge-beta, msedge-canary, msedge-dev
- Predeterminado: chrome
--caps <caps>: Lista separada por comas de capacidades a habilitar, valores posibles: tabs, pdf, history, wait, files, install. El valor predeterminado es todos.
--cdp-endpoint <endpoint>: Punto final CDP al que conectarse
--executable-path <path>: Ruta al ejecutable del navegador
--headless: Ejecutar el navegador en modo headless (con interfaz por defecto)
--device: Emular dispositivo móvil
--user-data-dir <path>: Ruta al directorio de datos de usuario
--port <port>: Puerto para escuchar en el transporte SSE
--host <host>: Host al que vincular el servidor. El valor predeterminado es localhost. Use 0.0.0.0 para vincular a todas las interfaces.
--allowed-origins <origins>: Lista separada por punto y coma de orígenes que el navegador puede solicitar. El valor predeterminado es permitir todos. Los orígenes que coincidan tanto con --allowed-origins como con --blocked-origins serán bloqueados.
--blocked-origins <origins>: Lista separada por punto y coma de orígenes que el navegador debe bloquear al solicitar. Los orígenes que coincidan tanto con --allowed-origins como con --blocked-origins serán bloqueados.
--vision: Ejecutar servidor que usa capturas de pantalla (las instantáneas Aria se usan por defecto)
--output-dir: Directorio para archivos de salida
--config <path>: Ruta al archivo de configuración

Perfil de usuario

Playwright MCP iniciará el navegador con el nuevo perfil, ubicado en

- `%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile` on Windows
- `~/Library/Caches/ms-playwright/mcp-{channel}-profile` on macOS
- `~/.cache/ms-playwright/mcp-{channel}-profile` on Linux

Toda la información de inicio de sesión se almacenará en ese perfil; puede eliminarlo entre sesiones si desea borrar el estado sin conexión.

Archivo de configuración

El servidor Playwright MCP se puede configurar mediante un archivo de configuración JSON. Aquí está el formato de configuración completo:

{
  // Browser configuration
  browser?: {
    // Browser type to use (chromium, firefox, or webkit)
    browserName?: 'chromium' | 'firefox' | 'webkit';

    // Path to user data directory for browser profile persistence
    userDataDir?: string;

    // Browser launch options (see Playwright docs)
    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
    launchOptions?: {
      channel?: string;        // Browser channel (e.g. 'chrome')
      headless?: boolean;      // Run in headless mode
      executablePath?: string; // Path to browser executable
      // ... other Playwright launch options
    };

    // Browser context options
    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
    contextOptions?: {
      viewport?: { width: number, height: number };
      // ... other Playwright context options
    };

    // CDP endpoint for connecting to existing browser
    cdpEndpoint?: string;

    // Remote Playwright server endpoint
    remoteEndpoint?: string;
  },

  // Server configuration
  server?: {
    port?: number;  // Port to listen on
    host?: string;  // Host to bind to (default: localhost)
  },

  // List of enabled capabilities
  capabilities?: Array<
    'core' |    // Core browser automation
    'tabs' |    // Tab management
    'pdf' |     // PDF generation
    'history' | // Browser history
    'wait' |    // Wait utilities
    'files' |   // File handling
    'install' | // Browser installation
    'testing'   // Testing
  >;

  // Enable vision mode (screenshots instead of accessibility snapshots)
  vision?: boolean;

  // Directory for output files
  outputDir?: string;

  // Network configuration
  network?: {
    // List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
    allowedOrigins?: string[];

    // List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
    blockedOrigins?: string[];
  };
 
  /**
   * Do not send image responses to the client.
   */
  noImageResponses?: boolean;
}

Puede especificar el archivo de configuración usando la opción de línea de comandos --config:

npx @hyhfish/mcp-hyh@latest --config path/to/config.json

Ejecución en Linux

Al ejecutar un navegador con interfaz en un sistema sin pantalla o desde procesos de trabajo de los IDE, ejecute el servidor MCP desde un entorno con DISPLAY y pase la bandera --port para habilitar el transporte SSE.

npx @hyhfish/mcp-hyh@latest --port 8931

Y luego, en la configuración del cliente MCP, establezca url en el punto final SSE:

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

Docker

NOTA: La implementación de Docker solo admite chromium headless por el momento.

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

Puede crear la imagen de Docker usted mismo.

docker build -t mcr.microsoft.com/playwright/mcp .

Uso programático

import http from 'http';

import { createServer } from '@hyhfish/mcp-hyh';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

  // Creates a headless Playwright MCP server with SSE transport
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.connect(transport);

  // ...
});

Modos de herramientas

Las herramientas están disponibles en dos modos:

Modo Instantánea (predeterminado): Utiliza instantáneas de accesibilidad para un mejor rendimiento y fiabilidad
Modo Visión: Utiliza capturas de pantalla para interacciones basadas en visual

Para usar el Modo Visión, agregue la bandera --vision al iniciar el servidor:

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

El Modo Visión funciona mejor con los modelos de uso de computadora que pueden interactuar con elementos usando el espacio de coordenadas X Y, basándose en la captura de pantalla proporcionada.

Interacciones basadas en instantáneas

browser_snapshot
- Título: Instantánea de página
- Descripción: Captura una instantánea de accesibilidad de la página actual; esto es mejor que una captura de pantalla
- Parámetros: Ninguno
- Solo lectura: true

browser_click
- Título: Clic
- Descripción: Realiza un clic en una página web
- Parámetros:
  - element (string): Descripción legible del elemento utilizada para obtener permiso para interactuar con el elemento
  - ref (string): Referencia exacta del elemento objetivo de la instantánea de página
- Solo lectura: false

browser_drag
- Título: Arrastrar mouse
- Descripción: Realiza arrastrar y soltar entre dos elementos
- Parámetros:
  - startElement (string): Descripción legible del elemento de origen utilizada para obtener permiso para interactuar con el elemento
  - startRef (string): Referencia exacta del elemento de origen de la instantánea de página
  - endElement (string): Descripción legible del elemento de destino utilizada para obtener permiso para interactuar con el elemento
  - endRef (string): Referencia exacta del elemento de destino de la instantánea de página
- Solo lectura: false

browser_hover
- Título: Pasar el mouse
- Descripción: Pasa el mouse sobre un elemento de la página
- Parámetros:
  - element (string): Descripción legible del elemento utilizada para obtener permiso para interactuar con el elemento
  - ref (string): Referencia exacta del elemento objetivo de la instantánea de página
- Solo lectura: true

browser_type
- Título: Escribir texto
- Descripción: Escribe texto en un elemento editable
- Parámetros:
  - element (string): Descripción legible del elemento utilizada para obtener permiso para interactuar con el elemento
  - ref (string): Referencia exacta del elemento objetivo de la instantánea de página
  - text (string): Texto para escribir en el elemento
  - submit (boolean, opcional): Si se debe enviar el texto ingresado (presionar Enter después)
  - slowly (boolean, opcional): Si se debe escribir un carácter a la vez. Útil para activar manejadores de teclas en la página. Por defecto, todo el texto se completa de una vez.
- Solo lectura: false

browser_select_option
- Título: Seleccionar opción
- Descripción: Selecciona una opción en un menú desplegable
- Parámetros:
  - element (string): Descripción legible del elemento utilizada para obtener permiso para interactuar con el elemento
  - ref (string): Referencia exacta del elemento objetivo de la instantánea de página
  - values (array): Matriz de valores para seleccionar en el menú desplegable. Puede ser un solo valor o varios valores.
- Solo lectura: false

browser_take_screenshot
- Título: Tomar una captura de pantalla
- Descripción: Toma una captura de pantalla de la página actual. No puede realizar acciones basadas en la captura de pantalla; use browser_snapshot para acciones.
- Parámetros:
  - raw (boolean, opcional): Si se debe devolver sin compresión (en formato PNG). El valor predeterminado es false, que devuelve una imagen JPEG.
  - filename (string, opcional): Nombre de archivo para guardar la captura de pantalla. El valor predeterminado es page-{timestamp}.{png|jpeg} si no se especifica.
  - element (string, opcional): Descripción legible del elemento utilizada para obtener permiso para capturar el elemento. Si no se proporciona, la captura se tomará del viewport. Si se proporciona el elemento, también se debe proporcionar la ref.
  - ref (string, opcional): Referencia exacta del elemento objetivo de la instantánea de página. Si no se proporciona, la captura se tomará del viewport. Si se proporciona la ref, también se debe proporcionar el elemento.
- Solo lectura: true

Interacciones basadas en visión

browser_screen_capture
- Título: Tomar una captura de pantalla
- Descripción: Toma una captura de pantalla de la página actual
- Parámetros: Ninguno
- Solo lectura: true

browser_screen_move_mouse
- Título: Mover mouse
- Descripción: Mueve el mouse a una posición determinada
- Parámetros:
  - element (string): Descripción legible del elemento utilizada para obtener permiso para interactuar con el elemento
  - x (number): Coordenada X
  - y (number): Coordenada Y
- Solo lectura: true

browser_screen_click
- Título: Clic
- Descripción: Hace clic con el botón izquierdo del mouse
- Parámetros:
  - element (string): Descripción legible del elemento utilizada para obtener permiso para interactuar con el elemento
  - x (number): Coordenada X
  - y (number): Coordenada Y
- Solo lectura: false

browser_screen_drag
- Título: Arrastrar mouse
- Descripción: Arrastra con el botón izquierdo del mouse
- Parámetros:
  - element (string): Descripción legible del elemento utilizada para obtener permiso para interactuar con el elemento
  - startX (number): Coordenada X inicial
  - startY (number): Coordenada Y inicial
  - endX (number): Coordenada X final
  - endY (number): Coordenada Y final
- Solo lectura: false

browser_screen_type
- Título: Escribir texto
- Descripción: Escribe texto
- Parámetros:
  - text (string): Texto para escribir en el elemento
  - submit (boolean, opcional): Si se debe enviar el texto ingresado (presionar Enter después)
- Solo lectura: false

Gestión de pestañas

browser_tab_list
- Título: Listar pestañas
- Descripción: Lista las pestañas del navegador
- Parámetros: Ninguno
- Solo lectura: true

browser_tab_new
- Título: Abrir una nueva pestaña
- Descripción: Abre una nueva pestaña
- Parámetros:
  - url (string, opcional): La URL a la que navegar en la nueva pestaña. Si no se proporciona, la nueva pestaña estará en blanco.
- Solo lectura: true

browser_tab_select
- Título: Seleccionar una pestaña
- Descripción: Selecciona una pestaña por índice
- Parámetros:
  - index (number): El índice de la pestaña a seleccionar
- Solo lectura: true

browser_tab_close
- Título: Cerrar una pestaña
- Descripción: Cierra una pestaña
- Parámetros:
  - index (number, opcional): El índice de la pestaña a cerrar. Cierra la pestaña actual si no se proporciona.
- Solo lectura: false

Navegación

browser_navigate
- Título: Navegar a una URL
- Descripción: Navega a una URL
- Parámetros:
  - url (string): La URL a la que navegar
  - userDataDir (string, opcional): Directorio de datos de usuario personalizado para el perfil del navegador
- Solo lectura: false

Mejora de funcionalidad: El parámetro userDataDir del comando browser_navigate es una funcionalidad mejorada basada en el proyecto original Playwright MCP de Microsoft. Este parámetro permite cambiar dinámicamente el directorio del perfil de usuario del navegador durante la navegación, sin necesidad de reiniciar todo el servicio. Cuando se especifica este parámetro, el navegador actual se cierra y se reinicia con el nuevo directorio de datos de usuario.

browser_navigate_back
- Título: Retroceder
- Descripción: Retrocede a la página anterior
- Parámetros: Ninguno
- Solo lectura: true

browser_navigate_forward
- Título: Avanzar
- Descripción: Avanza a la página siguiente
- Parámetros: Ninguno
- Solo lectura: true

Teclado

browser_press_key
- Título: Presionar una tecla
- Descripción: Presiona una tecla en el teclado
- Parámetros:
  - key (string): Nombre de la tecla a presionar o un carácter a generar, como ArrowLeft o a
- Solo lectura: false

Consola

browser_console_messages
- Título: Obtener mensajes de consola
- Descripción: Devuelve todos los mensajes de consola
- Parámetros: Ninguno
- Solo lectura: true

Archivos y medios

browser_file_upload
- Título: Subir archivos
- Descripción: Sube uno o varios archivos
- Parámetros:
  - paths (array): Las rutas absolutas a los archivos a subir. Puede ser un solo archivo o varios archivos.
- Solo lectura: false

browser_pdf_save
- Título: Guardar como PDF
- Descripción: Guardar la página como PDF
- Parámetros:
  - filename (string, opcional): Nombre de archivo para guardar el PDF. Por defecto es page-{timestamp}.pdf si no se especifica.
- Solo lectura: true

Utilidades

browser_close
- Título: Cerrar navegador
- Descripción: Cerrar la página
- Parámetros: Ninguno
- Solo lectura: true

browser_wait_for
- Título: Esperar
- Descripción: Esperar a que aparezca o desaparezca un texto o que pase un tiempo especificado
- Parámetros:
  - time (number, opcional): El tiempo de espera en segundos
  - text (string, opcional): El texto a esperar
  - textGone (string, opcional): El texto a esperar que desaparezca
- Solo lectura: true

browser_resize
- Título: Redimensionar ventana del navegador
- Descripción: Redimensionar la ventana del navegador
- Parámetros:
  - width (number): Ancho de la ventana del navegador
  - height (number): Alto de la ventana del navegador
- Solo lectura: true

browser_install
- Título: Instalar el navegador especificado en la configuración
- Descripción: Instala el navegador especificado en la configuración. Llama a esto si obtienes un error sobre que el navegador no está instalado.
- Parámetros: Ninguno
- Solo lectura: false

browser_handle_dialog
- Título: Manejar un diálogo
- Descripción: Manejar un diálogo
- Parámetros:
  - accept (boolean): Si se debe aceptar el diálogo.
  - promptText (string, opcional): El texto del mensaje en caso de un diálogo de aviso.
- Solo lectura: false

browser_network_requests
- Título: Listar solicitudes de red
- Descripción: Devuelve todas las solicitudes de red desde que se cargó la página
- Parámetros: Ninguno
- Solo lectura: true

Pruebas

browser_generate_playwright_test
- Título: Generar una prueba de Playwright
- Descripción: Generar una prueba de Playwright para el escenario dado
- Parámetros:
  - name (string): El nombre de la prueba
  - description (string): La descripción de la prueba
  - steps (array): Los pasos de la prueba
- Solo lectura: true

Playwright MCP

Documentación

Playwright MCP

Características clave

Casos de uso

Configuración de ejemplo

Tabla de contenido

Instalación en VS Code

Línea de comandos

Perfil de usuario

Archivo de configuración

Ejecución en Linux

Docker

Uso programático

Modos de herramientas

Interacciones basadas en instantáneas

Interacciones basadas en visión

Gestión de pestañas

Navegación

Teclado

Consola

Archivos y medios

Utilidades

Pruebas