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.

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)

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.
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.

Variable	Descripción	¿Requerido?	Valor predeterminado	Valor de ejemplo
Configuración de LLM
`MCP_MODEL_PROVIDER`	Proveedor de LLM a utilizar. Ver opciones a continuación.	Sí	`anthropic`	`openrouter`
`MCP_MODEL_NAME`	Nombre del modelo específico del proveedor elegido.	No	`claude-3-7-sonnet-20250219`	`anthropic/claude-3.7-sonnet`
`MCP_TEMPERATURE`	Temperatura LLM (0,0-2,0). Controla la aleatoriedad.	No	`0.0`	`0.7`
`MCP_TOOL_CALLING_METHOD`	Método para invocar herramientas ('auto', 'json_schema', 'function_calling'). Afecta `run_browser_agent` .	No	`auto`	`json_schema`
`MCP_MAX_INPUT_TOKENS`	Máximo de tokens de entrada para el contexto LLM para `run_browser_agent` .	No	`128000`	`64000`
`MCP_BASE_URL`	Opcional: Anulación genérica de la URL base del proveedor LLM.	No	Específico del proveedor	`http://localhost:8080/v1`
`MCP_API_KEY`	Opcional: Anulación genérica de la clave API del proveedor LLM (tiene prioridad sobre las claves específicas del proveedor).	No	-	`sk-...`
Claves API del proveedor	Obligatorio según `MCP_MODEL_PROVIDER` a menos que se configure `MCP_API_KEY` .
`OPENAI_API_KEY`	Clave API para OpenAI.	Si se utiliza	-	`sk-...`
`ANTHROPIC_API_KEY`	Clave API para Anthropic.	Si se utiliza	-	`sk-ant-...`
`GOOGLE_API_KEY`	Clave API para Google AI (Gemini).	Si se utiliza	-	`AIza...`
`AZURE_OPENAI_API_KEY`	Clave API para Azure OpenAI.	Si se utiliza	-	`...`
`DEEPSEEK_API_KEY`	Clave API para DeepSeek.	Si se utiliza	-	`sk-...`
`MISTRAL_API_KEY`	Clave API para Mistral AI.	Si se utiliza	-	`...`
`OPENROUTER_API_KEY`	Clave API para OpenRouter.	Si se utiliza	-	`sk-or-...`
`ALIBABA_API_KEY`	Clave API para Alibaba Cloud (DashScope).	Si se utiliza	-	`sk-...`
`MOONSHOT_API_KEY`	Clave API para Moonshot AI.	Si se utiliza	-	`sk-...`
`UNBOUND_API_KEY`	Clave API para Unbound AI.	Si se utiliza	-	`...`
Puntos finales del proveedor	Opcional: anular los puntos finales de API predeterminados.
`OPENAI_ENDPOINT`	URL del punto final de la API de OpenAI.	No	`https://api.openai.com/v1`
`ANTHROPIC_ENDPOINT`	URL del punto final de la API antrópica.	No	`https://api.anthropic.com`
`AZURE_OPENAI_ENDPOINT`	Obligatorio si se usa Azure. Su punto de conexión de recursos de Azure.	Si se utiliza	-	`https://res.openai.azure.com/`
`AZURE_OPENAI_API_VERSION`	Versión de la API de Azure.	No	`2025-01-01-preview`	`2023-12-01-preview`
`DEEPSEEK_ENDPOINT`	URL del punto final de la API de DeepSeek.	No	`https://api.deepseek.com`
`MISTRAL_ENDPOINT`	URL del punto final de la API de Mistral.	No	`https://api.mistral.ai/v1`
`OLLAMA_ENDPOINT`	URL del punto final de la API de Ollama.	No	`http://localhost:11434`	`http://ollama.local:11434`
`OPENROUTER_ENDPOINT`	URL del punto final de la API de OpenRouter.	No	`https://openrouter.ai/api/v1`
`ALIBABA_ENDPOINT`	URL del punto final de la API de Alibaba (DashScope).	No	`https://dashscope...v1`
`MOONSHOT_ENDPOINT`	URL del punto final de la API de Moonshot.	No	`https://api.moonshot.cn/v1`
`UNBOUND_ENDPOINT`	URL del punto final de la API de IA sin límites.	No	`https://api.getunbound.ai`
Ollama específico
`OLLAMA_NUM_CTX`	Tamaño de la ventana de contexto para los modelos Ollama.	No	`32000`	`8192`
`OLLAMA_NUM_PREDICT`	Máximo de tokens para predecir los modelos de Ollama.	No	`1024`	`2048`
Configuración del agente ( `run_browser_agent` )
`MCP_AGENT_TYPE`	Implementación del agente para `run_browser_agent` ('org' o 'custom').	No	`org`	`custom`
`MCP_MAX_STEPS`	Máximo de pasos por ejecución del agente.	No	`100`	`50`
`MCP_USE_VISION`	Habilitar capacidades de visión (análisis de captura de pantalla).	No	`true`	`false`
`MCP_MAX_ACTIONS_PER_STEP`	Máximo de acciones por paso del agente.	No	`5`	`10`
`MCP_KEEP_BROWSER_OPEN`	Mantenga abierto el navegador administrado por el servidor entre llamadas `run_browser_agent` (si `MCP_USE_OWN_BROWSER=false` ).	No	`false`	`true`
`MCP_ENABLE_RECORDING`	Habilitar la grabación de vídeo de Playwright para `run_browser_agent` .	No	`false`	`true`
`MCP_SAVE_RECORDING_PATH`	Ruta para guardar grabaciones de video de ejecución del agente (obligatorio si `MCP_ENABLE_RECORDING=true` ).	Si está grabando	-	`./tmp/recordings`
`MCP_AGENT_HISTORY_PATH`	Directorio para guardar archivos JSON del historial del agente.	No	`./tmp/agent_history`	`./agent_runs`
`MCP_HEADLESS`	Ejecute el navegador sin interfaz de usuario específicamente para la herramienta `run_browser_agent` .	No	`true`	`false`
`MCP_DISABLE_SECURITY`	Deshabilite las funciones de seguridad del navegador específicamente para la herramienta `run_browser_agent` (úsela con precaución).	No	`true`	`false`
Configuración de investigación profunda ( `run_deep_search` )
`MCP_RESEARCH_MAX_ITERATIONS`	Máximas iteraciones de búsqueda para una investigación profunda.	No	`10`	`5`
`MCP_RESEARCH_MAX_QUERY`	Máximo de consultas de búsqueda por iteración.	No	`3`	`5`
`MCP_RESEARCH_USE_OWN_BROWSER`	Utilice una instancia de navegador independiente para la investigación (requiere `CHROME_CDP` si `MCP_USE_OWN_BROWSER=true` ).	No	`false`	`true`
`MCP_RESEARCH_SAVE_DIR`	Directorio para guardar artefactos de investigación (informes, resultados).	No	`./tmp/deep_research/{task_id}`	`./research_output`
`MCP_RESEARCH_AGENT_MAX_STEPS`	Pasos máximos para subagentes dentro de una investigación profunda.	No	`10`	`15`
Configuración del navegador (anulaciones de herramientas generales y específicas)
`MCP_USE_OWN_BROWSER`	Establezca como verdadero para conectarse al navegador del usuario a través de `CHROME_CDP` en lugar de iniciar uno nuevo.	No	`false`	`true`
`CHROME_CDP`	Conéctate a Chrome mediante la URL del protocolo DevTools. Obligatorio si `MCP_USE_OWN_BROWSER=true` .	Si `MCP_USE_OWN_BROWSER=true`	-	`http://localhost:9222`
`BROWSER_HEADLESS`	Ejecutar el navegador sin la interfaz de usuario visible. Afecta principalmente `run_deep_search` . Véase también `MCP_HEADLESS` .	No	`true`	`false`
`BROWSER_DISABLE_SECURITY`	Configuración general de seguridad del navegador. Véase también `MCP_DISABLE_SECURITY` .	No	`false`	`true`
`CHROME_PATH`	Ruta al ejecutable de Chrome/Chromium.	No	-	`/usr/bin/chromium-browser`
`CHROME_USER_DATA`	Ruta al directorio de datos del usuario de Chrome (para sesiones persistentes, útil con `CHROME_CDP` ).	No	-	`~/.config/google-chrome/Profile 1`
`BROWSER_TRACE_PATH`	Directorio para guardar archivos de seguimiento de Playwright (útil para la depuración).	No	`./tmp/trace`	`./traces`
`BROWSER_WINDOW_WIDTH`	Ancho de la ventana del navegador (píxeles).	No	`1280`	`1920`
`BROWSER_WINDOW_HEIGHT`	Altura de la ventana del navegador (píxeles).	No	`720`	`1080`
Servidor y registro
`LOG_FILE`	Ruta para el archivo de registro del servidor.	No	`mcp_server_browser_use.log`	`/var/log/mcp_browser.log`
`BROWSER_USE_LOGGING_LEVEL`	Nivel de registro ( `DEBUG` , `INFO` , `WARNING` , `ERROR` , `CRITICAL` ).	No	`INFO`	`DEBUG`
`ANONYMIZED_TELEMETRY`	Habilitar/deshabilitar la telemetría anónima ( `true` / `false` ).	No	`true`	`false`

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:

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 .
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.
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.

Browser-Use MCP Server

Integrations