Chrome Browser MCP

Un puente local que permite que una aplicación privada de modo desarrollador de ChatGPT inspeccione y controle las pestañas ya abiertas en tu Google Chrome de escritorio.

Versión de parche actual: 0.1.2. Cada parche debe incrementar esta versión; CI rechaza parches que no lo hagan.

El puente expone 17 herramientas MCP:

• lecturas: browser_status, list_tabs, get_active_tab, read_tab, read_tabs, search_tabs

• acciones: click, type, fill_form, press_key, scroll, select_option, navigate, new_tab, close_tab

• agentes hijos de ChatGPT: spawn_chatgpt_agent, read_chatgpt_agent

spawn_chatgpt_agent abre una nueva pestaña de chatgpt.com en segundo plano por defecto, envía exactamente el prompt proporcionado por el usuario y devuelve su ID de pestaña. read_chatgpt_agent lee esa pestaña hija mediante el mismo extractor semántico acotado utilizado para las pestañas normales; llámalo de nuevo más tarde si el hijo aún está generando.

Los objetivos de las acciones aceptan un selector CSS o texto visible exacto / aria-label / placeholder / nombre / texto de etiqueta asociado. Los objetivos ambiguos fallan en lugar de adivinar.

El puente no expone cookies, almacenamiento local, almacenamiento de sesión, contraseñas guardadas, valores de entrada ocultos, ejecución arbitraria de JavaScript, páginas internas de Chrome ni pestañas de incógnito. No utiliza la API de depuración de Chrome.

Ruta probada

La prueba de extremo a extremo lanza un proceso real de Chromium con la extensión Manifest V3 sin empaquetar, inicia el host real de mensajería nativa, conecta un cliente MCP sobre Streamable HTTP, abre páginas en vivo, las lista y las lee, y verifica que un valor de entrada de contraseña no se devuelve. La cobertura de pruebas unitarias/integración valida las acciones de página, el enrutamiento MCP, el registro/composición de herramientas de agentes hijos de ChatGPT, la sincronización de la versión de la extensión generada y que los archivos de tiempo de ejecución utilizados por Chrome/mensajería nativa estén rastreados por Git.

MCP client
  -> http://127.0.0.1:2091/mcp
  -> native host process
  -> Chrome Native Messaging
  -> MV3 extension
  -> live Chrome tabs

Ejecuta todas las compuertas:

npm ci
npm run check

Related MCP server: sansan-chrome-mcp

Arquitectura

ChatGPT developer-mode app
          |
          | OpenAI Secure MCP Tunnel (outbound HTTPS)
          v
127.0.0.1:2091/mcp
          |
          | same local Node process
          v
Chrome Native Messaging host
          |
          v
Chrome MV3 extension
          |
          +-- chrome.tabs
          +-- chrome.scripting (isolated-world reads + actions)

Chrome inicia el host nativo cuando la extensión se conecta. El host nativo inicia el endpoint MCP de bucle local. Por lo tanto, Chrome debe estar abierto y la extensión debe estar habilitada siempre que ChatGPT use la aplicación.

Requisitos

• macOS

• Google Chrome 120+

• Node.js 20+

• Una cuenta de ChatGPT con Modo de desarrollador disponible

• Un ID de túnel de OpenAI Platform y una clave de API de tiempo de ejecución con permisos de Lectura y Uso de túneles

• tunnel-client

1. Instala el host nativo y carga la extensión una vez

npm run install:mac

Esto instala el manifiesto del host nativo en:

~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.komaksym.chrome_browser_mcp.json

Luego:

1. Abre chrome://extensions.

2. Activa Modo de desarrollador.

3. Haz clic en Cargar descomprimida.

4. Selecciona el directorio dist/extension de este repositorio.

5. Confirma que el ID de la extensión es exactamente:

jlpddlfiallighiohmhhkemgbhofpnha

No continúes si el ID difiere. El host nativo solo acepta ese origen exacto de la extensión.

2. Actualización de parches futuros

Seleccionas el directorio de la extensión solo una vez. La extensión compilada y el puente MCP en dist/ están confirmados en Git, y CI rechaza cambios de código fuente cuya compilación de tiempo de ejecución confirmada esté desactualizada.

Para cada parche posterior, el flujo de actualización normal es exactamente:

git pull

Luego abre chrome://extensions y haz clic en Actualizar. No selecciones la ruta de la extensión de nuevo ni ejecutes un comando de compilación separado solo para consumir un parche publicado.

git pull actualiza tanto dist/extension (lo que Chrome carga) como dist/bridge (lo que ejecuta el host nativo). Al hacer clic en Actualizar, se recarga la conexión de extensión/mensajería nativa sin empaquetar para que se use el tiempo de ejecución recién extraído.

La versión visible de la extensión debe cambiar en cada parche. Para este parche debe mostrar 0.1.2. Si aún muestra una versión anterior, el tiempo de ejecución extraído no se aplicó.

3. Verifica la cadena del navegador local

Mantén Chrome abierto y luego ejecuta:

npm run verify:local

Una verificación exitosa imprime:

• ID de la extensión;

• versión de la extensión;

• versión del servidor MCP;

• las 17 herramientas MCP anunciadas.

El verificador falla si las versiones de la extensión y MCP difieren, o si el puente es lo suficientemente antiguo como para no informar su versión MCP. Esto hace que un puente obsoleto de 15 herramientas sea inmediatamente distinguible de una extensión de Chrome obsoleta.

4. Configura el túnel MCP seguro

Crea un túnel y una clave de API de tiempo de ejecución en OpenAI Platform. Luego:

export CONTROL_PLANE_API_KEY="sk-..."
./scripts/configure-tunnel.sh tunnel_0123456789abcdef0123456789abcdef

tunnel-client doctor --profile chrome-browser-mcp --explain
tunnel-client run --profile chrome-browser-mcp

El perfil reenvía el túnel a:

http://127.0.0.1:2091/mcp

Mantén tunnel-client run activo siempre que ChatGPT necesite las herramientas del navegador.

5. Añádelo a ChatGPT

1. En ChatGPT, activa Configuración -> Seguridad e inicio de sesión -> Modo de desarrollador.

2. Abre Configuración -> Complementos.

3. Haz clic en + para crear una aplicación de modo desarrollador.

4. Elige Tunnel como tipo de conexión.

5. Selecciona o pega el ID del túnel.

6. Usa los metadatos de app-metadata.json.

7. Confirma que ChatGPT descubre las 17 herramientas.

8. En un chat nuevo, haz clic en + -> Más, selecciona Chrome Browser y luego pregunta: List my open Chrome tabs.

Consulta docs/CHATGPT_SETUP.md para la verificación exacta y la resolución de problemas.

Modelo de seguridad

El texto de la página web es datos, nunca autoridad. Cada resultado de contenido incluye un marcador explícito de contenido no confiable, y las instrucciones de las herramientas le dicen al modelo que nunca convierta instrucciones encontradas en páginas en acciones.

La extensión solicita intencionalmente acceso a todas las páginas HTTP y HTTPS para poder leer e interactuar con pestañas abiertas normales. El límite de protección es:

• la extensión se carga localmente por ti;

• Chrome solo lanza el host nativo exacto en la lista de permitidos;

• el host nativo rechaza cualquier origen excepto el ID de extensión estable;

• el endpoint MCP se vincula solo a 127.0.0.1;

• el túnel es solo de salida;

• las acciones se limitan a pestañas HTTP(S) normales y no exponen JavaScript arbitrario, acceso al depurador, cookies ni almacenamiento del navegador;

• los objetivos legibles por humanos ambiguos se rechazan en lugar de adivinarse.

Lee THREAT_MODEL.md y SECURITY_REVIEW.md antes de usarlo sin supervisión.

Limitaciones conocidas

• Un perfil de Chrome debe cargar la extensión a la vez; dos perfiles pueden competir por el puerto 2091.

• Las páginas internas de Chrome, las páginas de Chrome Web Store, las páginas file:// y las pestañas de incógnito no se pueden leer ni controlar.

• Los iframes de origen cruzado no se recorren.

• Las aplicaciones solo de lienzo y el visor de PDF integrado de Chrome pueden devolver poco texto semántico.

• El extractor devuelve el texto visible del documento principal, encabezados, enlaces y descripción, no HTML sin procesar. Las credenciales y fragmentos de URL se eliminan, y los parámetros de consulta sensibles se redactan.

• press_key usa eventos de teclado DOM; Enter y Escape obtienen un comportamiento común explícito, pero algunos sitios requieren entrada de teclado confiable del sistema operativo/CDP.

• El envío de agentes hijos de ChatGPT depende del compositor web actual de ChatGPT (#prompt-textarea) y del marcado del botón de enviar; un cambio futuro en la interfaz de ChatGPT puede requerir actualizar esos selectores.

• read_chatgpt_agent devuelve el texto semántico visible de la pestaña hija, no una respuesta privilegiada de la API de ChatGPT.

• La carga de archivos no se implementa intencionalmente porque hacerlo de manera general requeriría una superficie de sistema de archivos/depurador más potente.

Desarrollo

npm ci
npm run version:check
npm run typecheck
npm run lint
npm test
npm run artifacts:check
npm run test:e2e
npm audit