agent-browser-mcp

Un servicio MCP que permite a tu Agente operar directamente el "Chrome real que estás usando".

No es un navegador en sandbox, ni un simple extractor de páginas web; es una conexión con el Chrome que ya tienes abierto en tu equipo, conservando:

• Estado de inicio de sesión

• Cookies

• Pestañas abiertas

• Contexto real de la página

Ideal para escenarios como:

• Permitir que Hermes lea directamente tus páginas de Xiaohongshu, sistemas de backend, bases de conocimiento y paneles de administración.

• Automatizar sitios web donde ya has iniciado sesión, en lugar de volver a iniciar sesión en un navegador sin estado.

• Cambiar a CDP / operaciones reales de ratón y teclado cuando la automatización de navegador estándar es inestable.

• Tener en una sola herramienta MCP: escaneo de páginas, ejecución de JS, control CDP, capturas de pantalla y entrada física.

Resumen en una frase:

Este es un proyecto que empaqueta la "automatización de navegador real" como un MCP estándar, permitiendo que el Agente deje de operar solo en navegadores sandbox y pueda integrarse realmente en tu flujo de trabajo diario de navegación.

Resumen de capacidades principales

• Descubrimiento y cambio de pestañas de Chrome real

• Escaneo de páginas y extracción de contenido simplificado

• Ejecución de JavaScript dentro de la página

• Llamadas a comandos individuales / por lotes de CDP nativo

• Capturas de pantalla de la página / escritorio

• Lectura de cookies

• Movimiento, clic y arrastre del ratón

• Entrada de teclado y teclas de acceso rápido

Si deseas que clientes MCP como Hermes, Claude Desktop o Cursor operen directamente sobre tu navegador real, este proyecto está diseñado para ese escenario.

Qué puede hacer este MCP

Este proyecto empaqueta las capacidades de automatización de navegador real en herramientas MCP estándar. Las capacidades clave incluyen:

1. Navegación y pestañas del navegador

• Ver las pestañas reales conectadas actualmente

• Cambiar a una pestaña específica

• Abrir una URL en la pestaña actual

• Abrir una nueva pestaña

2. Lectura de páginas

• Escanear el contenido de la página actual

• Extraer HTML / texto simplificado

• Adecuado para leer flujos de información, listas de publicaciones y páginas de resultados de búsqueda

3. Ejecución de páginas y control CDP

• Ejecutar cualquier JavaScript en la página

• Llamar directamente al Protocolo de Chrome DevTools (CDP)

• Soporte para comandos individuales y por lotes

• Se puede utilizar para capturas de pantalla, consultas DOM, clics, carga de archivos y otras operaciones complejas

4. Capacidades de captura de pantalla

• Captura de pantalla de la página (vía CDP)

• Captura de pantalla del escritorio (para ayudar en operaciones reales de escritorio)

5. Entrada física real

• Movimiento del ratón

• Clic del ratón

• Arrastre del ratón

• Entrada de teclado

• Envío de teclas de acceso rápido

Este tipo de capacidades son muy adecuadas para manejar:

• Sitios web que deben mantener el estado de inicio de sesión

• Sitios web donde las herramientas de automatización de navegador comunes son fácilmente detectadas por controles de riesgo

• Escenarios que requieren clics reales / entrada de teclado real

• Escenarios que requieren la lectura de estructuras de página complejas

Escenarios adecuados

Por ejemplo:

• Usar Hermes para leer tu flujo de recomendaciones actual en la página de inicio de Xiaohongshu

• Abrir páginas de backend en el navegador real y extraer información

• Llamar a CDP para capturar una pantalla de la página

• Volver a operaciones reales de ratón/teclado cuando el JS de la página no es suficiente

• Permitir que el Agente opere directamente en sitios donde ya has iniciado sesión, en lugar de volver a iniciar sesión en un navegador sin estado

Principio de funcionamiento

El proyecto consta de tres capas:

1. Extensión de Chrome

• Inyectada en páginas web reales

• Accede a tabs / cookies / debugger / management a través de la API de Chrome

• Se comunica con el servicio de puente local

2. Puente local TMWebDriver

• Escucha por defecto:

  • WebSocket: 127.0.0.1:18765

  • HTTP: 127.0.0.1:18766

• Responsable de conectar la extensión, mantener la sesión y reenviar los resultados de ejecución

3. Servicio MCP

• Expone las capacidades del navegador como herramientas MCP

• Para ser llamadas directamente por clientes como Hermes, Claude Desktop, Cursor, etc.

Herramientas principales

Las principales herramientas MCP expuestas actualmente incluyen:

Navegador/Pestañas

• get_setup_status

• list_tabs

• switch_tab

• open_url

• open_new_tab

• extension_path

• list_extensions

Lectura/Ejecución de páginas

• scan_page

• execute_js

CDP y capturas de pantalla

• cdp_command

• cdp_batch

• get_cookies

• capture_page_screenshot

• capture_desktop_screenshot

Entrada física

• mouse_move

• mouse_click

• mouse_drag

• type_text

• hotkey

• pointer_info

Requisitos de instalación

Entorno recomendado:

• macOS o Windows

• Python 3.10+

• Google Chrome

• Cualquier cliente que soporte MCP, por ejemplo:

  • Hermes Agent

  • Claude Desktop

  • Cursor

Instalación

Después de clonar localmente, ejecuta:

cd agent-browser-mcp
pip install -e .

Si deseas construir el wheel antes de instalar:

python -m pip install --upgrade build
python -m build
pip install dist/agent_browser_mcp-0.1.0-py3-none-any.whl

Herramienta de línea de comandos

Después de la instalación, se proporciona una CLI:

agent-browser-mcp

Tiene varios subcomandos comunes:

Mostrar el directorio de la extensión de Chrome

agent-browser-mcp extension-path

Mostrar el fragmento de configuración de Hermes

agent-browser-mcp print-hermes-config

Diagnóstico del entorno

agent-browser-mcp doctor

Este comando generará un JSON para ayudarte a verificar:

• La ubicación del directorio de la extensión

• Si config.js se ha generado

• El estado de los puertos

• El número de pestañas conectadas actualmente

• Sugerencias para el siguiente paso

Instalación de la extensión de Chrome

Este proyecto incluye una extensión de Chrome "unpacked" que debe cargarse manualmente una vez.

Paso 1: Obtener el directorio de la extensión

agent-browser-mcp extension-path

Paso 2: Cargar en Chrome

Abre:

chrome://extensions

Luego:

• Activa el "Modo de desarrollador"

• Haz clic en "Cargar extensión descomprimida"

• Selecciona el directorio obtenido en el paso anterior

Paso 3: Abrir una página web normal

Ten cuidado de no quedarte en about:blank.

Por favor, abre una página web normal en Chrome, por ejemplo:

• https://www.baidu.com

• https://www.xiaohongshu.com

De lo contrario, no se establecerá una sesión válida.

Configuración de Hermes

Agrega la siguiente sección a ~/.hermes/config.yaml:

mcp_servers:
  agent_browser:
    command: agent-browser-mcp
    timeout: 120
    connect_timeout: 60

El proyecto también incluye archivos de ejemplo:

• examples/hermes-config.yaml

Después de configurar, reinicia Hermes o recarga el MCP.

Puedes verificarlo con el siguiente comando:

hermes mcp list
hermes mcp test agent_browser

Si la prueba es exitosa, Hermes podrá descubrir y llamar a estas herramientas de navegador.

Configuración de Claude Desktop / Cursor

El repositorio también incluye ejemplos:

• examples/claude-desktop-config.json

• examples/cursor-mcp.json

La estructura de configuración es muy simple, lo esencial es:

{
  "mcpServers": {
    "agent_browser": {
      "command": "agent-browser-mcp",
      "args": []
    }
  }
}

Flujo de uso típico

1. Instalar el paquete de Python

2. Cargar la extensión en Chrome

3. Abrir una página web real

4. Conectar este servicio en el cliente MCP

5. Comenzar a llamar a las herramientas del navegador

Por ejemplo, el Agente puede:

• Abrir la página de inicio de Xiaohongshu

• Leer el flujo de recomendaciones

• Escanear la lista de publicaciones

• Realizar una captura de pantalla CDP de la página

• Ejecutar operaciones reales de ratón/teclado cuando sea necesario

Advertencia de seguridad

Este proyecto opera sobre tu navegador real y tu escritorio real.

Esto significa que:

• El movimiento del ratón es real

• Los clics son reales

• La entrada es real

• Las teclas de acceso rápido son reales

• El estado de inicio de sesión en el navegador también es real

Por favor, úsalo solo en entornos de cliente MCP y Agente en los que confíes.

Preguntas frecuentes

1. Hermes puede ver el servicio MCP, pero no está conectado a ninguna pestaña

Por favor, verifica:

• Si la extensión ya se ha cargado en chrome://extensions

• Si hay una página web normal abierta en Chrome

• Si no te has quedado solo en about:blank

También puedes ejecutar:

agent-browser-mcp doctor

2. connected_tabs es 0

Generalmente se debe a una de las siguientes razones:

• La extensión no se cargó correctamente

• No hay una página web normal abierta actualmente

• La extensión acaba de recargarse y la página aún no se ha refrescado

Sugerencia:

• Refresca la página web actual

• Abre una nueva URL normal

• Ejecuta doctor una vez más

3. La entrada física no funciona en macOS

Por favor, otorga permisos del sistema a la terminal / cliente MCP:

• Accesibilidad

• Grabación de pantalla (si necesitas capturas de pantalla del escritorio)

4. hermes mcp test agent_browser falla

Por favor, verifica:

• Si el paquete se instaló correctamente

• Si agent-browser-mcp está en el PATH

• Si la configuración de Hermes es correcta

• Ejecuta agent-browser-mcp doctor para ver la salida de diagnóstico

Agradecimientos

Las capacidades de automatización de navegador de este proyecto se extrajeron y reempaquetaron como un servicio MCP desde la pila de navegador de GenericAgent.

Un agradecimiento especial al proyecto GenericAgent y a su autor por proporcionar las ideas de implementación originales y la fuente de las capacidades principales.

Dirección del proyecto original:

• https://github.com/lsdefine/GenericAgent

Las siguientes partes de este proyecto provienen o están adaptadas de GenericAgent:

• TMWebDriver.py

• simphtml.py

• Recursos de la extensión de Chrome tmwd_cdp_bridge

Si continúas desarrollando o publicando basándote en este proyecto, también se recomienda mantener los agradecimientos y la indicación de la fuente de GenericAgent.

Licencia

MIT