Agente de navegador MCP

Características

Automatización avanzada del navegador
- Navegue a cualquier URL con estrategias de carga personalizables
- Capturar capturas de pantalla de página completa o de elementos específicos
- Realizar interacciones DOM precisas (hacer clic, rellenar, seleccionar, pasar el cursor)
- Ejecutar JavaScript arbitrario en el contexto del navegador con captura de registros de la consola
Cliente API potente
- Ejecutar solicitudes HTTP (GET, POST, PUT, PATCH, DELETE)
- Configurar los encabezados de solicitud y el contenido del cuerpo
- Procesar datos de respuesta con formato JSON
- Manejo de errores con retroalimentación detallada
Gestión de recursos de MCP
- Acceder a los registros de la consola del navegador como recursos
- Recuperar capturas de pantalla a través de la interfaz de recursos de MCP
- Sesión persistente con instancia de navegador completa
Capacidades del agente de IA
- Encadenar múltiples operaciones del navegador para tareas complejas
- Siga instrucciones de varios pasos con recuperación inteligente de errores
- Automatización de tareas técnicas mediante instrucciones en lenguaje natural

Manifestación

Haga clic en cualquier marca de tiempo para saltar a esa sección del video.

00:00 - Búsqueda de MCP en Google
Navegación a la página principal de Google y búsqueda de "Protocolo de Contexto de Modelo". Demostración de Claude Desktop utilizando la integración de MCP para realizar una búsqueda web básica y procesar los resultados.

00:33 - Captura de pantalla
Captura de pantalla de los resultados de búsqueda con un nombre de archivo personalizado y su visualización en el Finder. Muestra cómo Claude puede capturar y guardar contenido visual de páginas web durante la automatización del navegador.

01:00 - Búsqueda en Wikipedia
Navega a Wikipedia.org y busca "Protocolo de Contexto de Modelo". Esto ilustra la capacidad de Claude para interactuar con diferentes sitios web y su funcionalidad de búsqueda mediante la integración de MCP.

01:38 - Interacción del menú desplegable I
Navegación a un sitio web de prueba (the-internet.herokuapp.com/dropdown) y selección de la "Opción 1" en un menú desplegable. Esto demuestra la capacidad de Claude para interactuar con los elementos del formulario y realizar selecciones.

01:56 - Interacción del menú desplegable II
Al cambiar la selección a "Opción 2" en el mismo menú desplegable, se demuestra la capacidad de Claude para manipular el mismo elemento de formulario varias veces y realizar diferentes selecciones.

02:09 - Completar el formulario de inicio de sesión
Navegación a una página de inicio de sesión (the-internet.herokuapp.com/login) y rellenado el campo de nombre de usuario con "tomsmith" y el de contraseña con "SuperSecretPassword!". Demostración de la automatización del llenado de formularios.

02:28 - Envío de inicio de sesión
Enviar las credenciales de inicio de sesión y completar el proceso de autenticación. Muestra la capacidad de Claude para activar el envío de formularios y navegar por procesos de varios pasos.

02:36 - Ejecución de solicitud de API
Se realiza una solicitud GET al punto final de la API JSONPlaceholder. Esto demuestra la capacidad de Claude para realizar llamadas directas a la API y procesar los datos devueltos mediante la integración con MCP.

Requisitos

Node.js 16 o superior
Escritorio de Claude
Dependencias del dramaturgo

Compatibilidad con navegadores

npm init playwright@latest

Este paquete incluye Playwright y las dependencias necesarias para ejecutar la automatización del navegador. Al ejecutar npm install , se instalarán las dependencias necesarias de Playwright. El paquete es compatible con los siguientes navegadores:

Chrome (predeterminado)
Firefox
Microsoft Edge
WebKit (motor Safari)

Al usar un navegador por primera vez, Playwright instalará automáticamente los controladores correspondientes según sea necesario. También puede instalarlos manualmente con los siguientes comandos:

npx playwright install chrome
npx playwright install firefox
npx playwright install webkit
npx playwright install msedge

Nota sobre Safari : Playwright no ofrece compatibilidad directa con el navegador Safari. En su lugar, utiliza WebKit, el motor de navegación que lo impulsa.
Nota sobre Edge : Al seleccionar Edge como tipo de navegador, el agente iniciará Microsoft Edge (no Chromium). Técnicamente, en Playwright, Edge se inicia usando la instancia del navegador Chromium con el parámetro de canal 'msedge', ya que Microsoft Edge se basa en Chromium.

Instalación

Instalación manual

Clonar o descargar este repositorio:

git clone https://github.com/imprvhub/mcp-browser-agent
cd mcp-browser-agent

Instalar dependencias:

npm install

Construir el proyecto:

npm run build

Ejecución del servidor MCP

Hay dos formas de ejecutar el servidor MCP:

Opción 1: Ejecutar manualmente

Abra una terminal o un símbolo del sistema
Navegar al directorio del proyecto
Ejecute el servidor directamente:

node dist/index.js

Mantenga esta ventana de terminal abierta mientras usa Claude Desktop. El servidor se ejecutará hasta que cierre la terminal.

Opción 2: Inicio automático con Claude Desktop (recomendado para uso habitual)

El Escritorio Claude puede iniciar automáticamente el servidor MCP cuando sea necesario. Para configurarlo:

Configuración

El archivo de configuración de Claude Desktop se encuentra en:

macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Ventanas : %APPDATA%\Claude\claude_desktop_config.json
Linux : ~/.config/Claude/claude_desktop_config.json

Edite este archivo para agregar la configuración MCP del Agente del Navegador. Si el archivo no existe, créelo:

{
  "mcpServers": {
    "browserAgent": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
      "--browser",
      "chrome"
    ]
    }
  }
}

Importante : Reemplace ABSOLUTE_PATH_TO_DIRECTORY con la ruta absoluta completa donde instaló el MCP

Ejemplo de macOS/Linux: /Users/username/mcp-browser-agent
Ejemplo de Windows: C:\\Users\\username\\mcp-browser-agent

Si ya tiene otros MCP configurados, simplemente añada la sección "browserAgent" dentro del objeto "mcpServers". A continuación, se muestra un ejemplo de configuración con varios MCP:

{
  "mcpServers": {
    "otherMcp1": {
      "command": "...",
      "args": ["..."]
    },
    "otherMcp2": {
      "command": "...",
      "args": ["..."]
    },
    "browserAgent": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
      "--browser",
      "chrome"
    ]
    }
  }
}

Selección del navegador

El Agente de Navegador MCP admite varios tipos de navegadores. De forma predeterminada, usa Chrome, pero puede especificar un navegador diferente de varias maneras:

Opción 1: Archivo de configuración

Cree o edite el archivo .mcp_browser_agent_config.json en su directorio de inicio:

{
  "browserType": "chrome"
}

Los valores admitidos para browserType son:

chrome : utiliza Chrome instalado (predeterminado)
firefox : utiliza el navegador Firefox 'Nightly'
webkit : utiliza el motor WebKit (Nota: no se trata del propio Safari, sino del motor de renderizado WebKit que impulsa a Safari)
edge - Utiliza Microsoft Edge

Nota sobre Safari : Playwright no ofrece compatibilidad directa con el navegador Safari. En su lugar, utiliza WebKit, el motor que impulsa Safari. La implementación de WebKit en Playwright ofrece una funcionalidad similar, pero no es idéntica a la experiencia con Safari.

Opción 2: Argumento de línea de comandos

Al iniciar el servidor MCP manualmente, puede especificar el tipo de navegador:

node dist/index.js --browser firefox

Opción 3: Variable de entorno

Establezca la variable de entorno MCP_BROWSER_TYPE :

MCP_BROWSER_TYPE=firefox node dist/index.js

Opción 4: Configuración del escritorio de Claude

Al configurar el MCP en claude_desktop_config.json de Claude Desktop, puede especificar el tipo de navegador:

{
  "mcpServers": {
    "browserAgent": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
        "--browser",
        "chrome"
      ]
    }
  }
}

Implementación técnica

El Agente de Navegador MCP se basa en el Protocolo de Contexto de Modelo, lo que permite a Claude interactuar con un navegador con interfaz gráfica a través de Playwright. La implementación consta de cuatro componentes principales:

Servidor (index.ts)
- Inicializa el servidor MCP con el protocolo estándar del Protocolo de Contexto de Modelo
- Configura las capacidades del servidor para herramientas y recursos
- Establece comunicación con Claude a través del transporte stdio
Registro de herramientas (tools.ts)
- Define esquemas de herramientas API y de navegador
- Especifica parámetros, reglas de validación y descripciones.
- Registra herramientas con el servidor MCP para el descubrimiento de Claude
Manejadores de solicitudes (handlers.ts)
- Gestiona solicitudes de protocolo MCP para herramientas y recursos
- Expone registros del navegador y capturas de pantalla como recursos consultables
- Envía las solicitudes de ejecución de herramientas a los controladores adecuados
Ejecutor (executor.ts)
- Administra el ciclo de vida del navegador y del cliente API.
- Implementa funciones de automatización del navegador utilizando Playwright
- Maneja solicitudes de API con manejo de errores y análisis de respuestas adecuados.
- Mantiene la sesión del navegador con estado entre comandos

Capacidades del agente

A diferencia de las integraciones básicas, MCP Browser Agent funciona como un verdadero agente de IA mediante lo siguiente:

Mantener el estado del navegador persistente en múltiples comandos
Captura de registros detallados de la consola para depuración
Almacenamiento de capturas de pantalla para referencia y revisión
Gestión de secuencias de interacción complejas
Proporcionar información detallada sobre errores para la recuperación
Apoyo a operaciones encadenadas para flujos de trabajo complejos

Herramientas disponibles

Herramientas del navegador

Nombre de la herramienta	Descripción	Parámetros
`browser_navigate`	Navegar a una URL	`url` (obligatorio), `timeout` , `waitUntil`
`browser_screenshot`	Captura de pantalla	`name` (obligatorio), `selector` , `fullPage` , `mask` , `savePath`
`browser_click`	Elemento de clic	`selector` (obligatorio)
`browser_fill`	Completar formulario de entrada	`selector` (obligatorio), `value` (obligatorio)
`browser_select`	Seleccione la opción desplegable	`selector` (obligatorio), `value` (obligatorio)
`browser_hover`	Pase el cursor sobre el elemento	`selector` (obligatorio)
`browser_evaluate`	Ejecutar JavaScript	`script` (requerido)

Herramientas API

Nombre de la herramienta	Descripción	Parámetros
`api_get`	Solicitud GET	`url` (obligatorio), `headers`
`api_post`	Solicitud POST	`url` (obligatorio), `data` (obligatorios), `headers`
`api_put`	Solicitud PUT	`url` (obligatorio), `data` (obligatorios), `headers`
`api_patch`	Solicitud de PATCH	`url` (obligatorio), `data` (obligatorios), `headers`
`api_delete`	Solicitud DELETE	`url` (obligatorio), `headers`

Acceso a recursos

El agente del navegador MCP expone los siguientes recursos:

browser://logs - Acceder a los registros de la consola del navegador
screenshot://[name] - Acceder a capturas de pantalla por nombre

Ejemplo de uso

A continuación se muestran algunos ejemplos realistas de cómo utilizar el agente de navegador MCP con Claude:

Navegación básica del navegador

Navigate to the Google homepage at https://www.google.com

Take a screenshot of the current page and name it "google-homepage"

Type "weather forecast" in the search box

Interacciones simples

Navigate to https://www.wikipedia.org and search for "Model Context Protocol"

Go to https://the-internet.herokuapp.com/dropdown and select the option "Option 1" from the dropdown

Llenado básico de formularios

Navigate to https://the-internet.herokuapp.com/login and fill in the username field with "tomsmith" and the password field with "SuperSecretPassword!"

Go to https://the-internet.herokuapp.com/login, fill in the username and password fields, then click the login button

Ejecución simple de JavaScript

Go to https://example.com and execute a JavaScript script to return the page title

Navigate to https://www.google.com and execute a JavaScript script to count the number of links on the page

Solicitudes de API básicas

Perform a GET request to https://jsonplaceholder.typicode.com/todos/1

Make a POST request to https://jsonplaceholder.typicode.com/posts with appropriate JSON data

Estos ejemplos representan las capacidades reales del Agente de Navegador MCP y son más realistas en cuanto a lo que puede lograr en su estado actual.

Solución de problemas

Error "Servidor desconectado"

Si ve el error "Agente del navegador MCP: Servidor desconectado" en Claude Desktop:

Verifique que el servidor esté ejecutándose :
- Abra una terminal y ejecute manualmente node dist/index.js desde el directorio del proyecto
- Si el servidor se inicia correctamente, utilice Claude mientras mantiene esta terminal abierta
Comprueba tu configuración :
- Asegúrese de que la ruta absoluta en claude_desktop_config.json sea correcta para su sistema
- Verifique nuevamente que haya utilizado barras invertidas dobles ( \\ ) para las rutas de Windows
- Verifique que esté utilizando la ruta completa desde la raíz de su sistema de archivos

El navegador no aparece

Si el navegador no se inicia o no lo ves:

Comprueba si el navegador especificado está instalado
- Verifique que tenga el navegador (Chrome, Firefox, Edge o Safari/WebKit) instalado en su sistema
- Los controladores del navegador son gestionados automáticamente por Playwright
Reinicie el servidor y Claude Desktop
- Elimine cualquier proceso de nodo existente que pueda estar ejecutando el servidor
- Reinicie Claude Desktop para establecer una nueva conexión

El proceso del navegador no se cierra correctamente

Existen problemas conocidos con los navegadores Chromium y Chrome donde el proceso a veces no finaliza correctamente después de su uso. Si experimenta este problema:

Cerrar manualmente el proceso del navegador :
- Windows : Presione Ctrl+Shift+Esc para abrir el Administrador de tareas, busque el proceso de Chrome/Chromium y finalícelo
- macOS : Abra el Monitor de actividad (Aplicaciones > Utilidades > Monitor de actividad), busque el proceso Chrome/Chromium y haga clic en la X para finalizarlo
- Linux : ejecute ps aux | grep chrome o ps aux | grep chromium para encontrar el proceso, luego kill <PID> para finalizarlo
Nota sobre la compatibilidad del navegador :
- Este problema se ha observado principalmente con Chromium y Chrome.
- Los navegadores integrados de Firefox y Playwright no suelen experimentar este problema.

[!PRECAUCIÓN] Esta integración de MCP se basa en Playwright, que presenta problemas y errores conocidos que pueden afectar su funcionamiento. Por favor, reporte cualquier problema que encuentre con la automatización del navegador a la sección de problemas de GitHub de Playwright . El equipo de Playwright trabaja continuamente para solucionar estos problemas, pero este agente proporciona la base para las funciones de automatización del navegador con Claude Desktop a pesar de estas limitaciones.

Desarrollo

Estructura del proyecto

src/index.ts : Punto de entrada principal e inicialización del servidor MCP
src/tools.ts : Esquemas y registro de herramientas
src/handlers.ts : controladores de solicitudes MCP para herramientas y recursos
src/executor.ts : Lógica de implementación de herramientas usando Playwright

Edificio

npm run build

Observando los cambios

npm run watch

Pruebas

El proyecto incluye pruebas para verificar la funcionalidad principal y el manejo del navegador.

npm test               # Run tests
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report

Las pruebas verifican la integridad de la configuración, las funciones de automatización del navegador, la gestión de errores y la limpieza de procesos. El conjunto de pruebas se centra especialmente en garantizar la correcta gestión de los procesos del navegador debido a problemas conocidos con la finalización de Chrome/Chromium.

Consideraciones de seguridad

[!PRECAUCIÓN] Esta integración de MCP proporciona a Claude funciones de control autónomo del navegador. Consulte nuestra Política de Seguridad para obtener información importante sobre usos prohibidos, implicaciones de seguridad y prácticas recomendadas.

El Agente de Navegador MCP está diseñado para tareas de automatización legítimas, pero podría ser objeto de un uso indebido. Los usuarios son responsables de garantizar que su uso cumpla con todas las leyes, términos de servicio y directrices éticas aplicables. Consulte nuestra Política de Seguridad detallada para obtener más información.

Contribuyendo

¡Agradecemos sus contribuciones al Agente del Navegador MCP! Aquí hay algunas áreas en las que puede colaborar:

Agregar nuevas capacidades de automatización del navegador
Mejorar la gestión y recuperación de errores
Mejorar la captura de pantalla y la gestión de recursos
Creación de flujos de trabajo y ejemplos útiles
Optimización del rendimiento para operaciones complejas

Licencia

Este proyecto está licenciado bajo la Licencia Pública de Mozilla 2.0: consulte el archivo de LICENCIA para obtener más detalles.

Integrations