Servidor MCP que utiliza el navegador

Nota del proyecto : Esta implementación del servidor MCP se basa en la base del uso del navegador y la interfaz web . La lógica principal de automatización del navegador y los patrones de configuración se adaptaron del proyecto original.

Servidor de automatización de navegador impulsado por IA que implementa el Protocolo de Contexto de Modelo (MCP) para el control del navegador en lenguaje natural y la investigación web.

Características

• 🧠 Integración MCP : implementación de protocolo completo para la comunicación del agente de IA.

• 🌐 Automatización del navegador : navegación de páginas, llenado de formularios, interacción de elementos a través de lenguaje natural (herramienta run_browser_agent ).

• 👁️ Comprensión visual : análisis de captura de pantalla opcional para LLM con capacidad visual.

• 🔄 Persistencia del estado : opción para administrar una sesión de navegador en múltiples llamadas MCP o conectarse al navegador del usuario.

• 🔌 Compatibilidad con múltiples LLM : se integra con OpenAI, Anthropic, Azure, DeepSeek, Google, Mistral, Ollama, OpenRouter, Alibaba, Moonshot, Unbound AI.

• 🔍 Herramienta de investigación profunda : herramienta dedicada a la investigación web de varios pasos y la generación de informes (herramienta run_deep_search ).

• ⚙️ Configuración de variables de entorno : totalmente configurable a través de variables de entorno.

• 🔗 Conexión CDP : capacidad de conectarse y controlar una instancia de Chrome/Chromium iniciada por el usuario a través del protocolo Chrome DevTools.

Related MCP server: Browserbase MCP Server

Inicio rápido

Prerrequisitos

• Python 3.11 o superior

• uv (instalador rápido de paquetes de Python): pip install uv

• Navegador Chrome/Chromium instalado

• Instalar navegadores Playwright: uv sync y luego uv run playwright install

Integración con clientes MCP (por ejemplo, Claude Desktop)

Puede configurar clientes como Claude Desktop para que se conecten a este servidor. Agregue la siguiente estructura a la configuración del cliente (p. ej., claude_desktop_config.json ) y ajuste la ruta y las variables de entorno según sea necesario:

// Example for Claude Desktop config
"mcpServers": {
    "browser-use": {
      // Option 1: Run installed package
      // "command": "uvx",
      // "args": ["mcp-server-browser-use"],

      // Option 2: Run from local development source
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-browser-use",
        "run",
        "mcp-server-browser-use"
      ],
      "env": {
        // --- CRITICAL: Add required API keys here ---
        "OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY",
        // "OPENAI_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENAI",
        // "ANTHROPIC_API_KEY": "YOUR_KEY_HERE_IF_USING_ANTHROPIC",
        // ... add other keys based on MCP_MODEL_PROVIDER ...

        // --- Optional Overrides (defaults are usually fine) ---
        "MCP_MODEL_PROVIDER": "openrouter", // Use OpenRouter as provider
        "MCP_MODEL_NAME": "google/gemini-2.5-pro-exp-03-25:free", // Example OpenRouter model
        "BROWSER_HEADLESS": "true",    // Default: run browser without UI
        "BROWSER_USE_LOGGING_LEVEL": "INFO",

        // --- Example for connecting to your own browser ---
        // "MCP_USE_OWN_BROWSER": "true",
        // "CHROME_CDP": "http://localhost:9222",

        // Ensure Python uses UTF-8
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1",
        "PYTHONUTF8": "1"
      }
    }
}

Importante: Asegúrese de que el command y args indiquen correctamente cómo desea ejecutar el servidor (ya sea desde el paquete instalado o desde el directorio de origen). Configure las claves de API necesarias en la sección env .

Herramientas MCP

Este servidor expone las siguientes herramientas a través del Protocolo de Contexto de Modelo:

Herramientas sincrónicas (esperar a que finalice)

1. run_browser_agent

   • Descripción: Ejecuta una tarea de automatización del navegador según instrucciones en lenguaje natural y espera a que se complete. Utiliza configuraciones con el prefijo MCP_ (p. ej., MCP_HEADLESS , MCP_MAX_STEPS ).

   • Argumentos:

     • task (cadena, obligatoria): la tarea o el objetivo principal.

     • add_infos (cadena, opcional): contexto adicional o sugerencias para el agente (utilizado por el tipo de agente custom ).

   • Devuelve: (cadena) El resultado final extraído por el agente o un mensaje de error.

2. run_deep_search

   • Descripción: Realiza una investigación web exhaustiva sobre un tema, genera un informe y espera a que finalice. Utiliza la configuración con el prefijo MCP_RESEARCH_ y la configuración general BROWSER_ (p. ej., BROWSER_HEADLESS ).

   • Argumentos:

     • research_task (cadena, obligatoria): el tema o la pregunta de la investigación.

     • max_search_iterations (entero, opcional, predeterminado: 10): máximo de ciclos de búsqueda.

     • max_query_per_iteration (entero, opcional, predeterminado: 3): máximo de consultas de búsqueda por ciclo.

   • Devuelve: (cadena) El informe de investigación generado en formato Markdown, incluida la ruta del archivo o un mensaje de error.

Configuración (variables de entorno)

Configure el servidor mediante variables de entorno. Puede configurarlas en su sistema o colocarlas en un archivo .env en la raíz del proyecto.

Proveedores LLM compatibles ( MCP_MODEL_PROVIDER ):

openai , azure_openai , anthropic , google , mistral , ollama , deepseek , openrouter , alibaba , moonshot , unbound

Conexión a su propio navegador (CDP)

En lugar de que el servidor inicie y administre su propia instancia de navegador, puedes conectarlo a un navegador Chrome/Chromium que inicies y administres tú mismo. Esto es útil para:

• Usando su perfil de navegador existente (cookies, inicios de sesión, extensiones).

• Observar la automatización directamente en su propia ventana del navegador.

• Depuración de escenarios complejos.

Pasos:

1. Iniciar Chrome/Chromium con la depuración remota activada: Abra la terminal o el símbolo del sistema y ejecute el comando correspondiente a su sistema operativo. Esto indica a Chrome que escuche las conexiones en un puerto específico (p. ej., 9222).

   • macOS:

     /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

     (Ajuste la ruta si Chrome está instalado en otro lugar)

   • Linux:

     google-chrome --remote-debugging-port=9222
     # or
     chromium-browser --remote-debugging-port=9222

   • Windows (símbolo del sistema):

     "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

     (Ajusta la ruta a tu instalación de Chrome si es necesario)

   • Ventanas (PowerShell):

     & "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

     (Ajusta la ruta a tu instalación de Chrome si es necesario)

   Nota: Si el puerto 9222 ya está en uso, elija un puerto diferente (por ejemplo, 9223) y use ese mismo puerto en la variable de entorno CHROME_CDP .

2. Configurar variables de entorno: configure las siguientes variables de entorno en su archivo .env o entorno del sistema antes de iniciar el servidor MCP:

   MCP_USE_OWN_BROWSER=true
   CHROME_CDP=http://localhost:9222 # Use the same port you launched Chrome with

   • MCP_USE_OWN_BROWSER=true : le indica al servidor que se conecte a un navegador existente en lugar de iniciar uno.

   • CHROME_CDP : especifica la URL donde el servidor puede conectarse al punto final del protocolo DevTools de su navegador.

3. Ejecute el servidor MCP: Inicie el servidor como de costumbre:

   uv run mcp-server-browser-use

Ahora, cuando utilice las herramientas run_browser_agent o run_deep_search , el servidor se conectará a su instancia de Chrome en ejecución en lugar de crear una nueva.

Consideraciones importantes:

• El navegador iniciado con --remote-debugging-port debe permanecer abierto mientras el servidor MCP se esté ejecutando y necesite interactuar con él.

• Asegúrese de que la URL CHROME_CDP sea accesible desde donde se ejecuta el servidor MCP (generalmente http://localhost:PORT si se ejecuta en la misma máquina).

• Usar su propio navegador implica que el servidor hereda su estado (pestañas abiertas, sesiones iniciadas). Tenga esto en cuenta durante la automatización.

• Las configuraciones como MCP_HEADLESS , BROWSER_HEADLESS y MCP_KEEP_BROWSER_OPEN se ignoran cuando MCP_USE_OWN_BROWSER=true . El tamaño de la ventana depende de la ventana de su navegador.

Desarrollo

# Install dev dependencies and sync project deps
uv sync --dev

# Install playwright browsers
uv run playwright install

# Run with debugger (Example connecting to own browser via CDP)
# 1. Launch Chrome: google-chrome --remote-debugging-port=9222
# 2. Run inspector command:
npx @modelcontextprotocol/inspector@latest \
  -e OPENROUTER_API_KEY=$OPENROUTER_API_KEY \
  -e MCP_MODEL_PROVIDER=openrouter \
  -e MCP_MODEL_NAME=anthropic/claude-3.7-sonnet \
  -e MCP_USE_OWN_BROWSER=true \
  -e CHROME_CDP=http://localhost:9222 \
  uv --directory . run mcp run src/mcp_server_browser_use/server.py
# Note: Change timeout in inspector's config panel if needed (default is 10 seconds)

Solución de problemas

• Conflictos del navegador : si no se utiliza CHROME_CDP ( MCP_USE_OWN_BROWSER=false ), asegúrese de que no se estén ejecutando otras instancias de Chrome en conflicto con el mismo directorio de datos de usuario si se especifica CHROME_USER_DATA .

• Problemas de conexión CDP : si se usa MCP_USE_OWN_BROWSER=true :

  • Verifique que Chrome se haya iniciado con el indicador --remote-debugging-port .

  • Asegúrese de que el puerto en CHROME_CDP coincida con el puerto utilizado al iniciar Chrome.

  • Compruebe si hay problemas de firewall que bloqueen la conexión al puerto especificado.

  • Asegúrese de que el navegador todavía esté funcionando.

• Errores de API : Verifique que la variable de entorno de clave de API ( OPENAI_API_KEY , ANTHROPIC_API_KEY , etc.) esté configurada correctamente para el MCP_MODEL_PROVIDER seleccionado, o que MCP_API_KEY esté configurada. Verifique las claves y los puntos de conexión ( AZURE_OPENAI_ENDPOINT es obligatorio para Azure).

• Problemas de visión : asegúrese de que MCP_USE_VISION=true si utiliza funciones de visión y que el modelo LLM seleccionado admita la visión.

• Problemas de dependencias : Ejecute uv sync para asegurarse de que todas las dependencias estén instaladas correctamente. Revise pyproject.toml .

• Registro : Consulte el archivo de registro especificado por LOG_FILE (predeterminado: mcp_server_browser_use.log ) para ver mensajes de error detallados. Aumente BROWSER_USE_LOGGING_LEVEL a DEBUG para obtener una salida más detallada.

Licencia

MIT - Ver LICENCIA para más detalles.