CDP Bridge MCP

CDP Bridge MCP

CDP Bridge MCP es un servicio puente que conecta clientes MCP con sesiones de navegador reales. Se integra con páginas del navegador a través de una extensión de Chromium complementaria, permitiendo que cualquier cliente de modelos grandes lea pestañas, escanee páginas, ejecute automatizaciones, tome capturas de pantalla y navegue de forma fluida y sencilla.

中文 | English

Video de demostración

Introducción al proyecto

CDP Bridge MCP es adecuado para escenarios donde se necesita que un modelo grande opere un navegador real. A diferencia del raspado HTTP sin estado, se conecta a páginas del navegador que ya has iniciado sesión y abierto, por lo que puede reutilizar el estado de inicio de sesión, las cookies, el estado de la página y los resultados de renderizado del frontend del navegador real.

CDP Bridge MCP también admite operaciones con múltiples perfiles en un solo equipo y múltiples usuarios.

Repositorio de código: https://github.com/Unagi-cq/cdp-bridge-mcp

Este proyecto está escrito y publicado en Python. MCP admite dos modos de transporte: stdio y streamable-http.

Ventajas del proyecto

¿Por qué usar CDP Bridge MCP en lugar de Playwright MCP, Kimi Bridge o Chrome DevTools MCP?

Playwright MCP y Chrome DevTools MCP son muy potentes, pero están más orientados a flujos de trabajo de "pruebas de automatización / protocolo de depuración / nuevas instancias de navegador". Kimi Bridge tiene permisos funcionales limitados y tiende a enviar capturas de pantalla a modelos de visión para completar tareas.

El objetivo de CDP Bridge MCP es diferente: se centra en permitir que productos LLM o Agent tomen el control de la sesión de navegador real que el usuario está utilizando.

• Reutiliza el estado de inicio de sesión real: CDP Bridge MCP se conecta a las pestañas del navegador que ya tienes abiertas y con sesión iniciada. Muchos sitios que requieren estado de cuenta no necesitan volver a iniciar sesión ni transferir cookies adicionales.
• Más adecuado para la colaboración diaria con el navegador: Playwright es mejor para flujos de automatización repetibles y scriptables, mientras que CDP Bridge MCP es más adecuado para que el LLM realice tareas interactivas en la página actual del usuario, como leer, analizar, juzgar antes de hacer clic, ejecutar scripts y tomar capturas de pantalla.
• El contenido de la página es más adecuado para el consumo del LLM: browser_scan simplifica el HTML de la página, filtrando scripts, estilos y elementos invisibles, conservando en la medida de lo posible el texto, los controles y la información estructural útiles para el modelo, reduciendo el desperdicio de tokens.
• Cadena de inicio ligera: Una vez que el servidor se publica en PyPI, se puede iniciar directamente con uvx cdp-bridge. El lado del navegador solo necesita cargar la extensión para conectarse. No es necesario escribir scripts de Playwright ni configurar parámetros de depuración para cada instancia del navegador.
• Adecuado para implementación remota y desarrollo de productos Agent: Si se usa el modo streamable-http, cdp-bridge se puede implementar como un servicio residente en un servidor remoto. El backend del Agent se conecta al servicio a través del endpoint HTTP de MCP, y la extensión del navegador del usuario se conecta al mismo servicio a través de WebSocket. De esta manera, el lado del producto no necesita alojar el navegador del usuario ni transferir el estado de la cuenta a la nube; el usuario solo necesita instalar la extensión y configurar Bridge Host, Port y Token, y el Agent puede completar lectura, análisis y operaciones automatizadas en la sesión de navegador real autorizada por el usuario.
• Admite la conexión paralela de múltiples perfiles de navegador en el mismo equipo: Si abres varios perfiles de Chrome / Chromium en el mismo equipo y configuras diferentes tokens para la extensión, el servidor los aislará en diferentes espacios de sesión. Esto significa que puedes tener múltiples cuentas conectadas simultáneamente en la misma plataforma y hacer que el Agent opere sus respectivas páginas de navegador reales.
• Admite la conexión simultánea de múltiples usuarios en diferentes equipos: Las extensiones de navegador de diferentes usuarios y equipos pueden conectarse al mismo servicio streamable-http, siempre que cada uno use un token diferente, pueden trabajar en paralelo sin interferencias. Adecuado para agentes de atención al cliente, equipos de operaciones, nodos de recopilación de datos o escenarios de colaboración remota.
• Cubre tanto el uso personal como los productos de equipo: Los usuarios individuales pueden usar el stdio + 127.0.0.1:18765 predeterminado para conectarse rápidamente al navegador local; los equipos o desarrolladores de productos pueden usar streamable-http + 远端域名 + WebSocket + token para construir un canal de control del navegador e integrar capacidades de navegador real en sus productos Agent, consolas de atención al cliente, backends de recopilación de datos o sistemas de automatización internos.

Por lo tanto, si tu objetivo es "hacer que el modelo controle un navegador de automatización iniciado específicamente", Playwright MCP es adecuado; si tu objetivo es "depurar Chrome u operar finamente el protocolo DevTools", Chrome DevTools MCP es adecuado; si tu objetivo es "hacer que el modelo o el producto Agent lea y opere las páginas de navegador reales que el usuario está usando actualmente", CDP Bridge MCP se acerca más a este escenario.

Arquitectura del sistema

graph TB
    subgraph Client["🖥️ MCP 客户端 / Agent"]
        ClientA["客户端 A<br/>Bearer token_a"]
        ClientB["客户端 B<br/>Bearer token_b"]
    end

    subgraph Server["⚙️ cdp-bridge MCP 服务 (Python)"]
        FastMCP["FastMCP<br/>stdio / streamable-http"]
        Middleware["Token Middleware<br/>Authorization Bearer"]
        TokenManager["TokenManager<br/>按 token 隔离用户上下文"]
        TMWD["TMWebDriver<br/>会话管理器"]
        WS["Extension WebSocket<br/>默认 127.0.0.1:18765"]
        HTTP["Extension HTTP Fallback<br/>默认 127.0.0.1:18766"]
        FastMCP --- Middleware
        Middleware --- TokenManager
        TokenManager --- TMWD
        TMWD --- WS
        TMWD --- HTTP
    end

    subgraph DeviceA["💻 同一台电脑（多个 Browser Profile）"]
        ProfileA1["Profile A1<br/>账号 A / token_a"]
        ProfileA2["Profile A2<br/>账号 B / token_b"]
    end

    subgraph DeviceB["🧑‍💻 另一台电脑（另一位用户）"]
        ProfileB1["Profile B1<br/>账号 C / token_c"]
    end

    subgraph BrowserRuntime["🌐 浏览器扩展与页面"]
        BG["background.js<br/>Service Worker"]
        CT["content.js<br/>Content Script"]
        Tabs["浏览器标签页<br/>真实登录态 / 多账号页面"]
    end

    ClientA <-->|"MCP 协议\nstreamable-http / stdio"| FastMCP
    ClientB <-->|"MCP 协议\nstreamable-http"| FastMCP

    ProfileA1 <-->|"扩展连接\ntoken_a"| WS
    ProfileA2 <-->|"扩展连接\ntoken_b"| WS
    ProfileB1 <-->|"扩展连接\ntoken_c"| WS

    WS <-->|"WebSocket (ext_ws)"| BG
    HTTP <-->|"HTTP 长轮询"| BG
    BG <-->|"chrome.scripting<br/>CDP Runtime.evaluate"| Tabs
    BG <-->|"chrome.runtime.sendMessage"| CT
    CT -->|"DOM 访问"| Tabs

Resumen del flujo de datos:

1. El cliente MCP se conecta al servicio cdp-bridge a través de stdio (subproceso) o streamable-http (endpoint HTTP); en el modo streamable-http, el cliente puede especificar su propio contexto de usuario mediante Authorization: Bearer <token>.
2. El Token Middleware del lado del servidor se encarga de extraer el token, y el TokenManager se encarga de aislar las sesiones por token; las solicitudes MCP y las conexiones de extensión del navegador bajo el mismo token se enrutan al mismo contexto.
3. TMWebDriver inicia el WebSocket para que la extensión del navegador se conecte (por defecto :18765) y el fallback HTTP interno (por defecto :18766); los usuarios en diferentes equipos o las extensiones de diferentes perfiles de navegador en el mismo equipo pueden conectarse simultáneamente.
4. Cada extensión de navegador informa su token y las pestañas abiertas al conectarse (modo ext_ws); el servidor aísla las páginas de navegador reales de diferentes perfiles, cuentas y usuarios en consecuencia.
5. Cuando se invoca una herramienta MCP (como browser_execute_js), el servidor solo envía el código JS a la sesión del navegador correspondiente al token actual; el background.js de la extensión prioriza la ejecución en el MAIN world de la página mediante chrome.scripting.executeScript, y si la página tiene restricciones CSP, degrada automáticamente a CDP Runtime.evaluate.
6. Los resultados de la ejecución se devuelven al servidor a través de WebSocket y luego al cliente correspondiente mediante el protocolo MCP; por lo tanto, se pueden operar múltiples cuentas de la misma plataforma simultáneamente, y también se admite el uso concurrente de múltiples usuarios en diferentes equipos sin interferencias.

Herramientas disponibles

El servicio MCP expone actualmente las siguientes 10 herramientas:

Uso rápido

El siguiente es el flujo de uso más rápido con la configuración predeterminada:

1. Instala uv.
2. Abre chrome://extensions/ en Chrome u otro navegador Chromium y activa el "modo desarrollador".
3. Haz clic en "Cargar extensión descomprimida" y selecciona la carpeta src/cdp_bridge/tmwd_cdp_bridge.
4. Agrega cdp-bridge en el cliente MCP.

Configura MCP en cualquier cliente:

{
  "mcpServers": {
    "cdp-bridge": {
      "command": "uvx",
      "args": ["cdp-bridge@latest"]
    }
  }
}

Después de la configuración, abre cualquier página en el navegador y luego pide al modelo en el cliente de modelos grandes que ejecute operaciones en la página. La extensión se conectará automáticamente al servicio WebSocket iniciado por el proceso MCP; si ves ERR_CONNECTION_REFUSED por primera vez, espera unos segundos y se reconectará automáticamente.

Uso detallado

Pasos de instalación

1. Carga la carpeta de la extensión del navegador src/cdp_bridge/tmwd_cdp_bridge proporcionada en el proyecto en Chrome u otro navegador Chromium.
2. Configura CDP Bridge MCP en el cliente MCP.

Luego puedes usarlo normalmente. A continuación se detallan los pasos de instalación anteriores.

Primer uso: Después de cargar la extensión, la primera conexión WebSocket generará un error ERR_CONNECTION_REFUSED, lo cual es normal. La extensión tiene un mecanismo de reconexión automática integrado (sondea cada ~5 segundos). Cuando detecta que el servicio backend se ha iniciado, se reconecta automáticamente sin necesidad de reiniciar la extensión manualmente.

Flujo de uso

1. Carga la extensión del navegador (consulta los pasos a continuación)
2. Configura el cliente MCP (consulta los pasos a continuación)
3. Usa cualquier herramienta del navegador (como browser_get_tabs); el servicio WebSocket estará listo automáticamente después de que se inicie el servicio MCP
4. La extensión del navegador se conectará automáticamente en unos segundos, y luego todas las herramientas funcionarán normalmente

Cargar el navegador

Carga en Chrome u otro navegador Chromium:

1. Abre chrome://extensions/.
2. Activa el "modo desarrollador".
3. Haz clic en "Cargar extensión descomprimida".
4. Selecciona la carpeta src/cdp_bridge/tmwd_cdp_bridge.

Por defecto, la extensión se conecta al servicio WebSocket local 127.0.0.1:18765.

La configuración de conexión se puede modificar en la ventana emergente de la extensión:

• Bridge Host: Puede ser 127.0.0.1, localhost o un nombre de dominio. Al usar un nombre de dominio, el puerto se puede omitir, por ejemplo, bridge.example.com.
• Port: Puerto WebSocket. Con la configuración local predeterminada es 18765; si MCP se inicia con --ws-port, aquí se debe usar el mismo puerto. Si se accede por dominio y el servicio usa el puerto WebSocket predeterminado, se puede dejar vacío.
• Token: En el modo multiusuario streamable-http, se usa para vincular la extensión del navegador y el cliente MCP al mismo contexto de usuario. Si se deja vacío, la extensión escribirá automáticamente el valor predeterminado __default__. Si usas un token Bearer para acceder al servicio MCP remoto, aquí debes ingresar exactamente el mismo token que el cliente.

Configurar MCP

Primero confirma que uv esté instalado en el equipo. CDP Bridge MCP se inicia mediante uvx cdp-bridge@latest.

Dos modos de transporte

CDP Bridge admite dos modos de transporte MCP, según el escenario de uso:

Parámetros de inicio

Nota: --ws-port es el puerto por el que la extensión del navegador se conecta al backend; --port es el puerto HTTP por el que el cliente MCP se conecta al backend. No son el mismo puerto.

Prueba con script

# stdio 模式（默认）
uvx cdp-bridge@latest

# stdio 模式，指定 WebSocket 端口
uvx cdp-bridge@latest --ws-port 18767

# streamable-http 模式，指定 MCP HTTP 端口
uvx cdp-bridge@latest --transport streamable-http --port 8000

# streamable-http 模式，同时指定 MCP HTTP 端口和浏览器扩展 WebSocket 端口
uvx cdp-bridge@latest --transport streamable-http --port 8000 --ws-port 18767

# streamable-http 模式，只允许指定 token 接入
uvx cdp-bridge@latest --transport streamable-http --port 8000 --tokens "team_alice,team_bob"

# streamable-http 模式，同时指定 MCP HTTP 端口和监听的ip，远程机器可通过172.25.240.1:8000访问运行的MCP Server
uvx cdp-bridge@latest --transport streamable-http --host 172.25.240.1 --port 8000

# 也可以通过环境变量传入 token 白名单
CDP_BRIDGE_TOKENS="team_alice,team_bob" uvx cdp-bridge@latest --transport streamable-http --port 8000

Si no se pasa --transport, se usa stdio por defecto. El modo stdio no tiene puerto HTTP MCP; la dirección del servicio MCP en el modo streamable-http es http://127.0.0.1:<port>/mcp.

Evaluación comparativa de MCP (V3)

V3 corrige el problema de V2 de "contar como éxito si el modelo devuelve cualquier texto no vacío", y usa reglas de aceptación a nivel de escenario, dividiendo los escenarios en comparación central determinista, diagnóstico de estado de inicio de sesión real y diagnóstico de pestañas. La comparación central registra la tasa de éxito, la calidad, la tasa de éxito de herramientas, las rondas de API, los tokens y el tiempo, y genera un informe Markdown y JSON estructurado. Por defecto, prueba el código fuente del espacio de trabajo actual y fija la versión de Playwright MCP para evitar la deriva de latest.

export ANTHROPIC_API_KEY="你的 API Key"
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"  # 可选
export ANTHROPIC_MODEL="deepseek-v4-pro"                       # 可选

# 只做前置检查和本地构建，不调用 LLM
uv run python reports/V-003-2026-08-09/eval_mcp_compare_v3.py --preflight --build-check

# 核心对比，默认每个场景重复 3 次
uv run python reports/V-003-2026-08-09/eval_mcp_compare_v3.py --repeats 3

# 加入真实登录态和标签页诊断场景
uv run python reports/V-003-2026-08-09/eval_mcp_compare_v3.py --suite all --repeats 3

Consulta el Informe de prueba V3 y el Script de evaluación V3. Al ejecutar el script, también se genera eval_results.json en el mismo directorio; por defecto no se guarda el texto completo de las herramientas para evitar escribir pestañas reales o privacidad de la página en los resultados. Si se requiere auditoría, se puede agregar --save-tool-output.

La muestra V3 del 2026-08-09 usa cdp-bridge 0.1.23, Playwright MCP 0.0.79 y deepseek-v4-pro, y en el modo core repite cada uno de los 3 escenarios 3 veces, ejecutando un total de 18 tareas. La tasa de éxito y la calidad promedio de ambas partes son 100% / 1.00.

La siguiente tabla enumera "tiempo mediano / llamadas de herramienta promedio / tasa de éxito de herramientas / tokens totales medianos":

En esta ejecución, Playwright tuvo menor tiempo y tokens en el escenario de extracción de contenido simple; CDP Bridge usó menos llamadas de herramienta y tokens en los escenarios de interacción y página externa, y logró un tiempo mediano más bajo y una mayor tasa de éxito de herramientas. Estos son resultados de extremo a extremo bajo un modelo, red y sesión de navegador específicos, y no representan una conclusión de rendimiento general; los escenarios de estado de inicio de sesión real y pestañas son elementos de diagnóstico y no se incluyeron en la clasificación de calidad central de esta ejecución.

export ANTHROPIC_API_KEY="你的 API Key"
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"  # 可选
export ANTHROPIC_MODEL="deepseek-v4-pro"                       # 可选

# 默认 3 个场景，每个场景重复 3 次
python reports/V-002-2026-07-12/eval_mcp_compare_v2.py

# 只测某个场景，或只测一侧
python reports/V-002-2026-07-12/eval_mcp_compare_v2.py --case numpy --repeats 3
python reports/V-002-2026-07-12/eval_mcp_compare_v2.py --cdp-only

# 只检查依赖并生成报告，不调用 LLM
python reports/V-002-2026-07-12/eval_mcp_compare_v2.py --preflight

Aislamiento de tokens y multiusuario

En el modo streamable-http, el servidor aísla los espacios de sesión del navegador por token.

• El cliente MCP envía el token a través del encabezado de solicitud HTTP: Authorization: Bearer <token>
• La extensión del navegador envía el mismo token a través del campo Token en la ventana emergente
• El token del cliente y el token de la extensión deben ser exactamente iguales, para que el servidor pueda enrutarlos al mismo contexto de usuario
• Si la extensión no tiene token, usará automáticamente el valor predeterminado __default__
• Si el servidor no tiene configurado --tokens, se puede conectar cualquier token; si se configura --tokens, solo se permiten los tokens de la lista blanca
• En el mismo equipo, puedes hacer que diferentes perfiles de navegador usen diferentes tokens para operar en paralelo múltiples cuentas de la misma plataforma
• En diferentes equipos, también puedes hacer que múltiples usuarios se conecten al mismo servicio streamable-http y se aíslen mediante diferentes tokens

Configuración estándar

Modo stdio:

{
  "mcpServers": {
    "cdp-bridge": {
      "command": "uvx",
      "args": ["cdp-bridge@latest"]
    }
  }
}

Si necesitas modificar el puerto WebSocket para la conexión de la extensión del navegador, agrega --ws-port a args:

{
  "mcpServers": {
    "cdp-bridge": {
      "command": "uvx",
      "args": ["cdp-bridge@latest", "--ws-port", "18767"]
    }
  }
}

Modo streamable-http:

Primero inicia el servicio:

uvx cdp-bridge@latest --transport streamable-http --port 8000

Si también necesitas modificar el puerto WebSocket para la conexión de la extensión del navegador:

uvx cdp-bridge@latest --transport streamable-http --port 8000 --ws-port 18767

Luego configura la conexión del cliente:

{
  "mcpServers": {
    "cdp-bridge": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Si habilitaste el aislamiento multiusuario, el cliente debe llevar explícitamente el token Bearer:

{
  "mcpServers": {
    "cdp-bridge": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer team_alice"
      }
    }
  }
}

En este caso, el campo Token en la ventana emergente de la extensión del navegador también debe completarse con team_alice.

Claude Code

Opción 1: Agregar desde la línea de comandos

# stdio 模式
claude mcp add cdp-bridge uvx cdp-bridge@latest

# streamable-http 模式（先启动服务，再注册）
claude mcp add cdp-bridge --transport streamable-http http://127.0.0.1:8000/mcp

Opción 2: Archivo de configuración (recomendado para el modo streamable-http)

Agrega la configuración mcpServers en ~/.claude.json:

{
  "mcpServers": {
    "cdp-bridge": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Nota: Al usar el archivo de configuración, primero debes iniciar el servicio cdp-bridge (uvx cdp-bridge@latest --transport streamable-http --port 8000 --ws-port 18765) y luego reiniciar Claude Code.

Codex

# stdio 模式
codex mcp add cdp-bridge uvx cdp-bridge@latest

# streamable-http 模式
codex mcp add cdp-bridge --transport streamable-http --url http://127.0.0.1:8000/mcp

opencode

Configura en ~/.config/opencode/opencode.json:

Modo stdio:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cdp-bridge": {
      "type": "local",
      "command": [
        "uvx",
        "cdp-bridge@latest"
      ],
      "enabled": true
    }
  }
}

Modo streamable-http:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cdp-bridge": {
      "type": "remote",
      "url": "http://127.0.0.1:8000/mcp",
      "enabled": true
    }
  }
}

OpenClaw

Puedes usar la CLI de OpenClaw para escribir la configuración de MCP:

# stdio 模式
openclaw mcp set cdp-bridge '{"command":"uvx","args":["cdp-bridge@latest"]}'

# streamable-http 模式
openclaw mcp set cdp-bridge '{"transport":"streamable-http","url":"http://remoteip:8000/mcp"}'

La estructura de configuración stdio equivalente:

{
  "mcp": {
    "servers": {
      "cdp-bridge": {
        "command": "uvx",
        "args": ["cdp-bridge@latest"]
      }
    }
  }
}

Notas

• Este proyecto requiere Python 3.10 o superior.
• La extensión del navegador tiene un mecanismo de reconexión automática integrado: después de un fallo de conexión inicial, seguirá sondeando el servicio WebSocket (cada ~5 segundos) y se reconectará automáticamente cuando el servicio MCP se inicie. Si ves ERR_CONNECTION_REFUSED, espera unos segundos y se recuperará automáticamente.
• La automatización de páginas se ejecuta en tu sesión de navegador real; conecta solo clientes MCP en los que confíes.

Agradecimientos

La extensión del navegador y parte del código de este proyecto se basan y provienen de GenericAgent. Agradecemos al autor original del proyecto por su trabajo de código abierto.