Control del Navegador Chrome

Control del perfil local de Chrome para hosts MCP stdio.

Este proyecto expone herramientas MCP de control del navegador a través de una extensión de Chrome Manifest V3 conectada a un broker WebSocket de bucle local. Configura tu host MCP para lanzar el adaptador stdio con el mismo token de emparejamiento que introduces en la extensión.

Repositorio: https://github.com/vkongv/chrome-browser-control

Requisitos previos

• Node.js 18+

• Google Chrome

Related MCP server: Tabrix

Instalación y configuración

Ruta recomendada: instala la CLI y luego ejecuta la configuración.

npm install -g chrome-browser-control
# or, without a global install:
npx -y chrome-browser-control setup

La CLI se instala como cbctl (nombre corto preferido) y también como chrome-browser-control.

cbctl setup
cbctl start
cbctl doctor

setup escribe ~/.chrome-browser-control/config.env (token de emparejamiento + puerto), copia la extensión sin empaquetar a ~/.chrome-browser-control/extension e imprime fragmentos de configuración para hosts MCP. No confirmes ese directorio en el repositorio.

Habilidad del agente (separada de npm)

La habilidad del agente en tiempo de ejecución bajo skills/chrome-browser-control/ no se incluye dentro del paquete npm. Después de instalar la CLI, obtén la habilidad de este repositorio (o de skills.sh) si tu host de agente utiliza habilidades.

Comandos de la CLI (cbctl o chrome-browser-control):

Desde un clon del repositorio (colaboradores):

git clone https://github.com/vkongv/chrome-browser-control.git
cd chrome-browser-control
npm install
npm run build
node dist/cli/main.js setup

Los comandos npm run broker / npm run mcp locales del repositorio siguen disponibles para desarrollo contra fuentes TypeScript (con .env.local opcional del repositorio).

Variables de entorno

• CHROME_BROWSER_CONTROL_TOKEN — Obligatoria. Token de emparejamiento de alta entropía compartido por el broker, el adaptador MCP y la ventana emergente de la extensión.

• CHROME_BROWSER_CONTROL_PORT — Puerto del broker WebSocket (por defecto 8765).

• CHROME_BROWSER_CONTROL_HOST — Host de bucle local para el broker (por defecto 127.0.0.1).

• CHROME_BROWSER_CONTROL_EXTENSION_ID — Opcional. Fija el broker a un ID de extensión instalada.

• CHROME_BROWSER_CONTROL_AUTOLOAD — Opcional. Establécelo a 1 para que mcp pueda iniciar un broker si no hay ninguno accesible (recuperación). Prefiere cbctl start para uso normal.

• CHROME_BROWSER_CONTROL_DISABLE_LOCAL_ENV — Opcional. Establécelo a 1 para omitir la carga de .env.local del repositorio.

La configuración de usuario se encuentra en ~/.chrome-browser-control/ y se carga antes que cualquier .env.local del repositorio. Las variables de entorno del proceso siempre tienen prioridad.

Comportamiento por defecto de MCP solo conexión: cbctl mcp se conecta a un broker ya en ejecución. Inicia el broker con cbctl start primero. Para recuperación, usa cbctl mcp --autoload o CHROME_BROWSER_CONTROL_AUTOLOAD=1.

Cargar la extensión

1. Abre Chrome con el perfil que quieres que controlen las herramientas MCP.

2. Ve a chrome://extensions.

3. Activa el modo de desarrollador.

4. Haz clic en "Cargar descomprimida".

5. Selecciona ~/.chrome-browser-control/extension (impreso por setup). Los colaboradores que editen fuentes pueden cargar extension/ desde el repositorio en su lugar.

6. Abre la ventana emergente de la extensión Chrome Browser Control.

7. Mantén la URL del puente en ws://127.0.0.1:8765 a menos que hayas cambiado el puerto local.

8. Pega el token de emparejamiento generado.

9. Añade orígenes permitidos como https://example.com, http://localhost:3000 o * para todas las páginas normales http:// y https://.

10. Haz clic en "Guardar y reconectar".

La extensión puede solicitar permiso de host para los orígenes permitidos. Denegar esa solicitud impide las acciones de página para esos orígenes.

Usar * es conveniente para desarrollo local, pero expone cada página web normal del perfil actual de Chrome a las herramientas MCP. Prefiere orígenes explícitos cuando solo necesites unos pocos sitios. El modo comodín también solicita el permiso de host opcional <all_urls> para que Chrome permita capturas de pantalla del viewport visible mediante chrome.tabs.captureVisibleTab; el fondo sigue bloqueando URLs no http(s) y orígenes no permitidos antes de la captura.

Configuración del host MCP

Pega un fragmento de cbctl setup (o mcp-config) en Cursor, Claude Desktop, Codex u otro host MCP stdio. Para imprimir de nuevo la configuración específica del host más tarde:

cbctl mcp-config --host cursor
cbctl mcp-config --host claude
cbctl mcp-config --host codex
cbctl mcp-config --host yaml

La clave del servidor MCP es chrome_browser_control. El comando del adaptador es la CLI instalable (cbctl preferido) con args: ["mcp"] — no tsx contra server/index.ts.

Ejemplo en estilo YAML:

mcp_servers:
  chrome_browser_control:
    command: "cbctl"
    args: ["mcp"]
    env:
      CHROME_BROWSER_CONTROL_TOKEN: "<generated-token>"
      CHROME_BROWSER_CONTROL_PORT: "8765"
    timeout: 60
    connect_timeout: 30

Ejemplo en estilo JSON:

{
  "mcpServers": {
    "chrome_browser_control": {
      "command": "cbctl",
      "args": ["mcp"],
      "env": {
        "CHROME_BROWSER_CONTROL_TOKEN": "<generated-token>",
        "CHROME_BROWSER_CONTROL_PORT": "8765"
      }
    }
  }
}

Si la CLI no está en PATH, usa el respaldo NPX impreso por setup: npx con args: ["-y", "chrome-browser-control", "mcp"].

Si tu host MCP usa un archivo de configuración, mantenlo privado y fuera del repositorio.

Verificación

1. Inicia el broker: cbctl start

2. Ejecuta el verificador de configuración: cbctl doctor

3. Confirma desde tu host MCP llamando a la herramienta browser_status. Cuando esté listo, extension.status y ping.status deben reflejar una conexión de puente activa, y extension.allowedOrigins debe mostrar tu ámbito configurado.

Herramientas

• browser_status: comprueba si el adaptador MCP puede alcanzar el broker y si la extensión de Chrome responde a ping. Cuando está listo, extension.status y ping.status reflejan la conexión de puente activa (no un valor por defecto obsoleto desconectado), extension.allowedOrigins muestra el ámbito configurado (incluyendo * (todos los orígenes web http/https) cuando el modo comodín está activado), extension.session muestra el nombre de sesión/pestañas reclamadas, y protocolVersion / features confirman el código de la extensión descomprimida cargada. La versión de protocolo 6 incluye el marcador de característica document-targeting.

• name_session: establece un nombre de sesión legible para estado/depuración.

• list_tabs: lista pestañas cuyo origen de URL está permitido en la ventana emergente de la extensión. Cuando todas las pestañas abiertas están filtradas, devuelve { tabs: [], detail, hiddenTabCount, allowedOrigins? } en lugar de un [] vacío. El modo comodín se etiqueta claramente en allowedOrigins.

• list_frames: lista los documentos de marco actuales para una pestaña permitida usando el registro de marcos de Chrome. Los documentos HTTP(S) activos operables incluyen un documentId; las filas bloqueadas por política, con permiso de host denegado, no compatibles, con vallas y no activas conservan solo jerarquía/estado y redactan URL e identidad del documento.

• claim_tab: reclama una pestaña permitida para esta sesión de control del navegador y devuelve un sessionTabId. Las reclamaciones son estado de enrutamiento, no bloqueos exclusivos del navegador.

• release_tab: libera una reclamación por sessionTabId o tabId sin cerrar la pestaña.

• finalize_tabs: libera el estado de reclamación de la sesión sin cerrar pestañas. Pasa entradas keep para preservar reclamaciones de entrega/traspaso.

• snapshot: devuelve una instantánea DOM simplificada para un documento permitido. Por defecto es una instantánea de automatización compacta que incluye elementos accionables concisos, una vista previa de texto (500 caracteres), recuentos omitidos y resúmenes de regiones. Pasa mode: "full" para metadatos de elementos detallados y un campo text (4000 caracteres por defecto). Pasa mode: "visible" para elementos conscientes del viewport/intersección con límites y metadatos de desplazamiento. Pasa textLimit (hasta 100000) cuando necesites más texto del cuerpo de la página — comprueba textBytesOmitted para ver si el contenido fue truncado.

• visible_snapshot: herramienta de conveniencia para snapshot({ mode: "visible" }).

• navigate: navega la pestaña activa o un tabId especificado a una URL permitida, luego espera a que la pestaña termine de cargar cuando sea posible. Por defecto el foco no cambia (las pestañas en segundo plano permanecen en segundo plano; la pestaña enfocada no se desactiva). Pasa active: true solo cuando la pestaña deba volverse visible. Si la carga agota el tiempo, el resultado incluye pending: true y una warning. Admite observaciones after después de la espera de carga.

• click: hace clic en un elemento por referencia de instantánea en una pestaña permitida. Admite observaciones after.

• type: escribe en un elemento por referencia de instantánea en una pestaña permitida. Los campos tipo contraseña están bloqueados a menos que force=true. Admite observaciones after.

• scroll: desplaza una pestaña permitida por deltaX y deltaY. Las coordenadas opcionales x/y del viewport desplazan un elemento desplazable bajo ese punto cuando se encuentra uno. El desplazamiento no pagina el texto de la instantánea — las instantáneas usan el innerText completo de document.body. Aumenta textLimit en snapshot en lugar de unir desplazamientos a menos que la página cargue contenido de forma diferida. Admite observaciones after.

• query_elements: devuelve referencias/roles/etiquetas/límites acotados para elementos filtrados por selector CSS, rol, texto y visibilidad.

• extract_elements: extrae datos acotados de texto/html/enlaces/tiempo de un selector CSS. La extracción HTML redacta valores de atributos de contraseña/OTP/token oculto y marca elementos sensibles en lugar de filtrar valores secretos. Esta es la alternativa compatible con la evaluación de JavaScript sin procesar.

• screenshot: captura el viewport visible de una pestaña permitida como URL de datos. ref o bounds opcionales (+ padding) recortan después de la captura; los recortes vacíos fallan antes de captureVisibleTab. Las respuestas sin recortar omiten los campos de recorte. La captura MV3 es solo del viewport; las pestañas objetivo inactivas pueden activarse antes de la captura. Chrome requiere <all_urls> o activeTab para captureVisibleTab; esta extensión solicita <all_urls> opcional solo en modo comodín (*), por lo que las capturas de pantalla en modo comodín necesitan esa concesión de la ventana emergente.

• keypress: envía eventos de teclado DOM comunes a la página. Los atajos a nivel de navegador/SO no están garantizados bajo MV3. Admite observaciones after.

• click_at: envía eventos de ratón en coordenadas del viewport. Admite observaciones after.

• wait_for: espera condiciones acotadas de selector/texto/subcadena de URL y devuelve evidencia de coincidencia/tiempo de espera.

• page_status: devuelve título, URL, estado de listo/visibilidad, estado de viewport/desplazamiento y recuentos de recursos por tipo de iniciador. No expone cabeceras de solicitud ni cuerpos de respuesta.

• console_logs: devuelve registros de consola acotados capturados después de la inyección del script de contenido. No puede ver el historial de consola anterior de la página.

• collect_scroll: desplaza un número acotado de pasos (límite máximo cuando until está establecido), extrae elementos seleccionados en cada paso, opcionalmente apunta a un contenedor de desplazamiento anidado mediante scroll, aplica un límite agregado de elementos (maxItems, por defecto 100) y opcionalmente deduplica por texto o href para feeds diferidos. until.noNewItemsForSteps / until.stopBeforeDatetime opcionales (ISO-8601; requiere includeTimes) establecen stoppedReason. Los resultados incluyen recuentos omitidos/truncados. Admite observaciones after.

• perform_actions: ejecuta hasta 10 acciones de página secuenciales (click, type, scroll, keypress) en un solo viaje de ida y vuelta del broker. Falla rápido en el primer error de paso; las observaciones after terminales se ejecutan solo cuando cada paso tiene éxito. Los clics coordinados permanecen en la herramienta única click_at. Los pasos no pueden llevar after, tabId o sessionTabId.

Segmentación de documentos de marco

Las herramientas DOM/contenido aceptan un documentId opcional devuelto por list_frames. Omitirlo preserva el comportamiento existente y apunta al documento superior actual para cada operación. Proporcionarlo selecciona ese documento exacto: si el iframe navega, desaparece, se mueve a otra pestaña, se vuelve no compatible o pierde acceso, la operación falla en lugar de recurrir al marco superior o a un reemplazo que use el mismo frameId.

Cada resultado de contenido incluye documentId, frameId, isTopFrame y coordinateSpace verificados por el origen. Las coordenadas del marco superior usan tabViewport; los límites de visible_snapshot de iframe, click_at y el desplazamiento de coordenadas usan frameViewport. Los límites locales de iframe no se pueden pasar al recorte de capturas de pantalla porque screenshot sigue siendo una herramienta exclusiva del viewport de la pestaña. navigate, screenshot y list_frames solo aceptan destinos de pestaña; perform_actions.documentId se aplica a todo el lote y no se puede anular en un paso individual.

Los fallos de documento conservan uno de estos prefijos, incluso dentro de errores de pasos de lote y fallos de after: DOCUMENT_STALE:, DOCUMENT_POLICY_DENIED:, DOCUMENT_HOST_PERMISSION_DENIED: o DOCUMENT_UNSUPPORTED:. La V1 solo admite documentos HTTP(S) activos del marco principal o secundario. Excluye intencionadamente about:blank, about:srcdoc, blob:, data:, marcos de reserva de origen, navegación de iframe y la traducción de coordenadas de captura de pantalla de iframe a pestaña.

Actuar y luego observar

Las herramientas de acción navigate, click, type, scroll, keypress, click_at, collect_scroll y perform_actions aceptan un objeto after opcional. La extensión elimina after antes de enviar la acción base al script de contenido y luego ejecuta las observaciones solicitadas en este orden fijo: waitFor, snapshot, pageStatus. La respuesta es el resultado de la acción base más un objeto after con los resultados de la observación.

Para perform_actions, after se aplica solo a todo el lote: los pasos individuales no pueden incluir after, y las observaciones finales se omiten cuando falla algún paso. Los fallos parciales de lotes devuelven resultados de pasos estructurados con failedIndex y completedCount, mientras que conservan el éxito a nivel de puente para que los agentes puedan inspeccionar la carga útil.

{
  "ref": "h12",
  "after": {
    "waitFor": { "selector": ".results", "timeoutMs": 5000 },
    "snapshot": { "mode": "visible", "limit": 40 },
    "pageStatus": true
  }
}

after.waitFor debe incluir al menos uno de text, selector o urlIncludes; timeoutMs es opcional y tiene un límite máximo de 20000 para que toda la cadena de actuar y luego observar permanezca dentro del tiempo de espera de solicitud del broker por defecto. after.snapshot puede ser true para opciones de instantánea predeterminadas o un objeto con mode, textLimit y/o limit. Las solicitudes after no válidas se rechazan antes de que se ejecute la acción base.

Si la acción base se ejecuta correctamente, pero una observación after falla, la respuesta sigue incluyendo el resultado de la acción base y establece after en { "ok": false, "error": "..." }.

Modos de instantánea y referencias

Las instantáneas compactas predeterminadas están diseñadas para reducir el uso del contexto del modelo, preservando al mismo tiempo la automatización del navegador. Una instantánea compacta tiene el siguiente aspecto:

{
  "title": "Example Domain",
  "url": "https://example.com/",
  "mode": "compact",
  "elements": [{ "ref": "h1", "role": "link", "label": "Learn more" }],
  "omittedElements": 0,
  "textPreview": "Example Domain ...",
  "textBytesOmitted": 0,
  "regions": []
}

Use el modo completo solo cuando necesite los metadatos de elementos detallados heredados:

{ "mode": "full", "tabId": 123 }

Use el modo visible para trabajos limitados al viewport, páginas virtualizadas y planificación de coordenadas de clic:

{ "mode": "visible", "sessionTabId": "tab-1" }

Para leer contenido largo de una página (por ejemplo, documentación de API), aumente textLimit en lugar de usar scripts del broker o soluciones de CDP:

{ "mode": "full", "textLimit": 100000, "tabId": 123 }

El modo compacto también respeta textLimit; el texto del cuerpo se devuelve en textPreview (no hay campo text en modo compacto). Cuando textBytesOmitted es mayor que cero, aumente textLimit o desplácese por la página y vuelva a tomar una instantánea solo si el contenido se carga de forma diferida debajo del pliegue.

Las referencias son identificadores en memoria por documento (h...) asignados desde la identidad del elemento, no desde el orden de salida. Permanecen estables ante inserciones/reordenaciones del DOM en el mismo documento, y click/type se resuelven a través del almacén de referencias del script de contenido. Las referencias pueden colisionar entre documentos de marco, por lo que debe conservar el documentId del resultado y pasarlo con acciones de iframe posteriores. Navegar a una página diferente carga un nuevo documento, por lo que es probable que las referencias antiguas fallen limpiamente; tome una instantánea nueva después de la navegación o de cambios importantes en la página. El almacén de referencias elimina las entradas desconectadas, caducadas y que superan la capacidad, y elimina los atributos data-cbc-ref obsoletos para que las referencias eliminadas no puedan reutilizarse accidentalmente.

Sesiones de pestaña

Prefiera claim_tab antes de realizar trabajos de navegador de varios pasos:

{ "tabId": 123 }

El sessionTabId devuelto se puede pasar a snapshot, navigate, click, type, scroll, query_elements, extract_elements, screenshot, wait_for y herramientas de página relacionadas. Si una sesión tiene una reclamación actual, las acciones de página sin un tabId o sessionTabId explícito se dirigen a esa reclamación. Si no existe ninguna reclamación, se mantiene la reserva de pestaña activa heredada.

Las reclamaciones son solo estado de enrutamiento MCP indicativo. No impiden que el usuario cambie, cierre o navegue por una pestaña. Use release_tab o finalize_tabs cuando una tarea esté completa; ninguna de las herramientas cierra pestañas del navegador.

Comprobaciones de desarrollo

npm test
npm run build
cbctl doctor
# or: node dist/cli/main.js doctor
npm run benchmark:compact-snapshots
npm audit

npm run benchmark:snapshots es un alias para el mismo punto de referencia compacto vs. completo. El punto de referencia imprime bytes compactos, bytes completos y el porcentaje de reducción; el modo compacto debe mantenerse al menos un 50% más pequeño en el fixture denso.

Después de editar archivos en extension/, vuelva a cargar la extensión desempaquetada en chrome://extensions antes de ejecutar las comprobaciones e2e del navegador. Después de cambios en el adaptador/servidor, reconstruya y reinicie también el host MCP. Un service worker de fondo o un catálogo de herramientas obsoleto puede seguir sirviendo comportamientos antiguos; browser_status debe informar adapter.registeredToolCount: 24, la versión 6 del protocolo de la extensión y el marcador de característica document-targeting cuando ambos lados están actualizados.

Limitaciones

• Este es un prototipo con un token local compartido, no una autenticación multiusuario.

• Las llamadas a herramientas del navegador se serializan globalmente en el broker.

• Los scripts de contenido usan instantáneas del DOM, no el árbol de accesibilidad completo de Chrome.

• Las referencias son identificadores en memoria con ámbito de documento. Ejecute snapshot de nuevo después de la navegación, las recargas, los cambios importantes del DOM o los errores de referencias obsoletas.

• Las capturas de pantalla visibles son solo del viewport. Capturar una pestaña inactiva puede activarla porque Chrome MV3 captura la pestaña visible en una ventana.

• La captura de pantalla de Chrome requiere <all_urls> o activeTab. Este proyecto solicita <all_urls> opcional como permiso de host solo para capturas de pantalla con comodines. Si screenshot informa que falta este permiso, vuelva a cargar la extensión después de las actualizaciones del manifiesto, abra la ventana emergente, guarde la configuración y conceda la solicitud.

• keypress y click_at usan eventos del DOM, no el envío de entrada de CDP. Son útiles para los controladores de página, pero es posible que no activen los accesos directos privilegiados del navegador ni todas las rutas de entrada específicas del framework.

• Los registros de la consola se capturan solo después de la inyección del script de contenido y están limitados.

• Los resúmenes de recursos son solo recuentos de la API de rendimiento; los encabezados de solicitud, los cuerpos de respuesta, las cookies, el almacenamiento, el historial, los marcadores y las descargas no se exponen intencionadamente.

• El historial del navegador, los marcadores, las descargas y las herramientas de cookies no se exponen intencionadamente.

Seguridad

• No se acepta ningún token por defecto. Establezca CHROME_BROWSER_CONTROL_TOKEN en un valor seguro de alta entropía apto para URL tanto para el broker como para el adaptador MCP, luego pegue el mismo valor en la ventana emergente de la extensión.

• El broker solo se vincula a hosts de bucle local: 127.0.0.1, localhost o ::1.

• La extensión solo se conecta a ws://127.0.0.1, ws://localhost o ws://[::1] con un puerto opcional.

• El acceso a la página está limitado por los orígenes permitidos configurados en la ventana emergente. Use entradas explícitas como https://example.com, o introduzca * para permitir todas las páginas web normales http:// y https://. Las pestañas y acciones de página fuera del ámbito configurado están bloqueadas.

• Las comprobaciones de orígenes permitidos se realizan en el fondo de la extensión antes de las acciones de contenido, las capturas de pantalla y las reclamaciones de pestañas.

• Los campos de contraseña y OTP se detectan por tipo de entrada, autocompletado, nombres, ID, etiquetas y marcadores de posición. type los bloquea a menos que force=true.

• El CHROME_BROWSER_CONTROL_EXTENSION_ID opcional fija el broker a un ID de extensión instalado.

• La reserva de CDP no es compatible con el adaptador MCP porque elude el emparejamiento de la extensión.

Nunca vincule el broker a una interfaz que no sea de bucle local ni confirme tokens, archivos de configuración local, registros o notas de configuración personal.

Publicación del mantenedor

Los primeros lanzamientos públicos de npm son manuales. Los mantenedores siguen docs/publish-checklist.md. No agregue publicación automática al enviar ni tokens npm de larga duración en CI para la ruta de lanzamiento predeterminada.