CDP Bridge MCP

CDP Bridge MCP

O CDP Bridge MCP é um serviço de ponte que conecta clientes MCP a sessões reais de navegador, integrando-se às páginas do navegador por meio de uma extensão complementar do Chromium. Assim, qualquer cliente de modelo de linguagem grande pode ler abas, escanear páginas, executar automações, capturar telas e navegar de forma fluida e simples.

Português | English

Vídeos de demonstração

Introdução ao projeto

O CDP Bridge MCP é ideal para cenários em que você precisa que um modelo de linguagem grande opere um navegador real. Diferente de scraping HTTP sem estado, ele se conecta a páginas do navegador que já estão abertas e com login realizado, permitindo reutilizar o estado de autenticação, os cookies, o estado da página e o resultado da renderização front-end do navegador real.

O CDP Bridge MCP também oferece suporte à operação com múltiplos perfis em um único computador, bem como a múltiplos usuários.

Repositório do código: https://github.com/Unagi-cq/cdp-bridge-mcp

Este projeto é escrito e publicado em Python. O MCP oferece suporte aos modos de transporte stdio e streamable-http.

Vantagens do projeto

Por que usar o CDP Bridge MCP em vez do Playwright MCP, do Kimi Bridge ou do Chrome DevTools MCP?

O Playwright MCP e o Chrome DevTools MCP são muito poderosos, mas se inclinam mais para fluxos de trabalho de "testes de automação / protocolo de depuração / abertura de novas instâncias do navegador". O Kimi Bridge tem permissões limitadas e tende a concluir tarefas enviando capturas de tela para modelos de visão.

O objetivo do CDP Bridge MCP é diferente: ele tem mais foco em permitir que produtos de LLM ou de Agent assumam o controle da sessão real do navegador que o usuário está usando.

• Reutiliza o estado de autenticação real: o CDP Bridge MCP se conecta às abas do navegador que você já abriu e nas quais já fez login. Em muitos sites que exigem autenticação, não é necessário fazer login novamente ou copiar cookies manualmente.
• Mais adequado para colaboração diária com o navegador: o Playwright é mais apropriado para fluxos de automação repetíveis e scriptáveis, enquanto o CDP Bridge MCP é mais adequado para tarefas interativas do LLM na página atual do usuário, como leitura, análise, julgamento antes de clicar, execução de scripts e captura de tela.
• Conteúdo da página mais adequado para consumo por LLM: o browser_scan simplifica o HTML da página, filtrando scripts, estilos e elementos invisíveis, preservando ao máximo o texto, os controles e as informações estruturais úteis para o modelo e reduzindo o desperdício de tokens.
• Cadeia de inicialização leve: depois que o servidor é publicado no PyPI, ele pode ser iniciado diretamente com uvx cdp-bridge, e basta carregar a extensão no navegador para conectar. Não é necessário escrever scripts do Playwright nem configurar parâmetros de depuração separadamente para cada instância do navegador.
• Adequado para implantação remota e desenvolvimento de produtos Agent: se você usar o modo streamable-http, o cdp-bridge pode ser implantado como um serviço residente em um servidor remoto. O backend do Agent se conecta ao serviço por meio do endpoint HTTP do MCP, e a extensão do navegador do usuário se conecta ao mesmo serviço via WebSocket. Assim, o lado do produto não precisa hospedar o navegador do usuário nem migrar o estado da conta para a nuvem; o usuário só precisa instalar a extensão e configurar Bridge Host, Port e Token, e o Agent poderá realizar leitura, análise e automação na sessão real do navegador autorizada pelo usuário.
• Suporte à conexão paralela de vários perfis de navegador no mesmo computador: se você abrir vários perfis do Chrome/Chromium no mesmo computador e configurar tokens diferentes para a extensão em cada um, eles serão isolados pelo servidor em espaços de sessão separados. Isso significa que você pode manter várias contas conectadas simultaneamente na mesma plataforma e deixar o Agent operar as respectivas páginas reais do navegador.
• Suporte à conexão simultânea de múltiplos usuários em computadores diferentes: extensões de navegador em computadores e de usuários diferentes podem se conectar ao mesmo serviço streamable-http, desde que cada uma use um token distinto, trabalhando em paralelo sem interferência mútua. Isso é adequado para atendimento, equipes de operações, nós de coleta de dados ou cenários de colaboração remota.
• Atende tanto ao uso pessoal quanto a produtos de equipe: usuários individuais podem usar o stdio + 127.0.0.1:18765 padrão para integrar rapidamente o navegador local; equipes ou desenvolvedores de produtos podem usar o streamable-http + 远端域名 + WebSocket + token para criar um canal de controle do navegador, integrando recursos de navegador real aos seus próprios produtos Agent, painéis de atendimento, backends de coleta de dados ou sistemas internos de automação.

Portanto, se o seu objetivo é "fazer o modelo controlar um navegador de automação iniciado especificamente", o Playwright MCP é muito adequado; se o seu objetivo é "depurar o Chrome ou operar finamente o protocolo DevTools", o Chrome DevTools MCP é muito adequado; se o seu objetivo é "permitir que o modelo ou um produto Agent leia e opere as páginas reais do navegador que o usuário está usando no momento", o CDP Bridge MCP é mais próximo desse cenário.

Arquitetura do 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

Resumo do fluxo de dados:

1. O cliente MCP se conecta ao serviço cdp-bridge via stdio (subprocesso) ou streamable-http (endpoint HTTP); no modo streamable-http, o cliente pode especificar seu próprio contexto de usuário por meio de Authorization: Bearer <token>.
2. No servidor, o Token Middleware é responsável por extrair o token, e o TokenManager isola as sessões por token; as solicitações MCP e as conexões da extensão do navegador sob o mesmo token são roteadas para o mesmo contexto.
3. O TMWebDriver inicia o WebSocket para conexão da extensão do navegador (padrão :18765) e o fallback HTTP interno (padrão :18766); usuários em computadores diferentes, ou extensões de Perfis de Navegador diferentes no mesmo computador, podem se conectar simultaneamente.
4. Cada extensão do navegador informa seu token e as abas abertas ao se conectar (modo ext_ws); com base nisso, o servidor isola as páginas reais do navegador de perfis, contas e usuários diferentes.
5. Quando uma ferramenta MCP é chamada (por exemplo, browser_execute_js), o servidor envia o código JS apenas para a sessão do navegador correspondente ao token atual; o background.js da extensão executa primeiro via chrome.scripting.executeScript no mundo MAIN da página; se a página tiver restrições de CSP, ele faz downgrade automático para CDP Runtime.evaluate.
6. O resultado da execução é retornado ao servidor via WebSocket e, em seguida, devolvido ao cliente correspondente pelo protocolo MCP; portanto, é possível operar várias contas da mesma plataforma simultaneamente e também suportar o uso concorrente de múltiplos usuários em vários computadores sem interferência.

Ferramentas disponíveis

O serviço MCP atualmente expõe as 10 ferramentas a seguir:

Uso rápido

O fluxo mais rápido com a configuração padrão é o seguinte:

1. Instale o uv.
2. Abra chrome://extensions/ no Chrome ou em outro navegador Chromium e ative o "Modo do desenvolvedor".
3. Clique em "Carregar extensão descompactada" e selecione a pasta src/cdp_bridge/tmwd_cdp_bridge.
4. Adicione o cdp-bridge no cliente MCP.

Para configurar o MCP em qualquer cliente:

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

Após a configuração, abra qualquer página no navegador e peça ao modelo no cliente de LLM para executar operações na página. A extensão se conectará automaticamente ao serviço WebSocket iniciado pelo processo MCP; se você vir ERR_CONNECTION_REFUSED na primeira vez, aguarde alguns segundos e a reconexão automática acontecerá.

Uso detalhado

Etapas de instalação

1. Carregue a pasta da extensão do navegador fornecida no projeto, src/cdp_bridge/tmwd_cdp_bridge, no Chrome ou em outro navegador Chromium.
2. Configure o CDP Bridge MCP no cliente MCP.

Depois disso, é só usar. As etapas de instalação acima são detalhadas a seguir.

Primeiro uso: ao carregar a extensão, a primeira conexão WebSocket pode gerar o erro ERR_CONNECTION_REFUSED, o que é normal. A extensão tem um mecanismo interno de reconexão automática (sonda a cada ~5 segundos); quando detecta que o serviço de backend foi iniciado, ela restaura a conexão automaticamente, sem precisar reiniciar a extensão manualmente.

Fluxo de uso

1. Carregue a extensão do navegador (consulte as etapas abaixo)
2. Configure o cliente MCP (consulte as etapas abaixo)
3. Use qualquer ferramenta do navegador (por exemplo, browser_get_tabs); o serviço WebSocket fica automaticamente pronto após o serviço MCP ser iniciado
4. A extensão do navegador se conecta automaticamente em poucos segundos e, a partir daí, todas as ferramentas podem ser usadas normalmente

Carregar o navegador

Para carregar no Chrome ou em outro navegador Chromium:

1. Abra chrome://extensions/.
2. Ative o "Modo do desenvolvedor".
3. Clique em "Carregar extensão descompactada".
4. Selecione a pasta src/cdp_bridge/tmwd_cdp_bridge.

Por padrão, a extensão se conecta ao serviço WebSocket local 127.0.0.1:18765.

A configuração de conexão pode ser alterada no pop-up da extensão:

• Bridge Host: pode ser preenchido com 127.0.0.1, localhost ou um domínio. Ao preencher um domínio, a porta pode ser omitida, por exemplo bridge.example.com.
• Port: porta do WebSocket. Na configuração local padrão, é 18765; se o MCP foi iniciado com --ws-port, aqui deve ser informada a mesma porta. Em acesso por domínio, quando o serviço usa a porta WebSocket padrão, pode ser deixado em branco.
• Token: no modo multiusuário do streamable-http, é usado para vincular a extensão do navegador e o cliente MCP ao mesmo contexto de usuário. Se deixado em branco, a extensão grava automaticamente o valor padrão __default__. Se você usa Bearer token para acessar um serviço MCP remoto, aqui deve ser informado exatamente o mesmo token usado no cliente.

Configurar o MCP

Primeiro, confirme que o uv está instalado no computador. O CDP Bridge MCP é iniciado por meio do uvx cdp-bridge@latest.

Dois modos de transporte

O CDP Bridge oferece suporte a dois modos de transporte MCP, que podem ser escolhidos conforme o cenário de uso:

Parâmetros de inicialização

Observação: o --ws-port é a porta pela qual a extensão do navegador se conecta ao backend; o --port é a porta HTTP pela qual o cliente MCP se conecta ao backend. São portas diferentes.

Teste do 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

Quando --transport não é informado, o padrão usado é stdio. O modo stdio não tem porta HTTP do MCP; o endereço do serviço MCP no modo streamable-http é http://127.0.0.1:<port>/mcp.

Avaliação comparativa do MCP (V3)

A V3 corrigiu o problema estatístico da V2, que considerava "sucesso" qualquer retorno de texto não vazio do modelo, e passou a usar regras de aceite por cenário, dividindo os cenários em comparação central determinística, diagnóstico com estado de login real e diagnóstico de abas. A comparação central registra taxa de aprovação, qualidade, taxa de sucesso das ferramentas, rodadas de API, tokens e tempo de execução, além de gerar relatórios em Markdown e JSON estruturado. Por padrão, o teste usa o código-fonte do workspace atual e fixa a versão do Playwright MCP, evitando a 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

Consulte o Relatório de teste V3 e o Script de avaliação V3. Ao executar o script, também é gerado eval_results.json no mesmo diretório; por padrão, o texto completo das ferramentas não é salvo, para evitar gravar abas reais ou a privacidade das páginas no resultado. Se uma auditoria for realmente necessária, adicione --save-tool-output.

Na amostra V3 de 09/08/2026, foram usados cdp-bridge 0.1.23, Playwright MCP 0.0.79 e deepseek-v4-pro, no modo core, com 3 repetições para cada um dos 3 cenários, totalizando 18 execuções de tarefas. A taxa de aprovação e a qualidade média dos dois lados foram de 100% / 1,00.

A tabela a seguir lista, nesta ordem, "tempo mediano / chamadas médias de ferramentas / taxa de sucesso das ferramentas / total mediano de tokens":

Nesta execução, o Playwright apresentou menor tempo e menos tokens no cenário simples de extração de conteúdo; o CDP Bridge usou menos chamadas de ferramentas e menos tokens nos cenários de interação e página externa, além de obter menor tempo mediano e maior taxa de sucesso das ferramentas. Esses são resultados de ponta a ponta com modelos, redes e sessões de navegador específicos e não representam uma conclusão geral de desempenho; os cenários de login real e de abas são itens de diagnóstico e não entraram no ranking de qualidade central desta execução.

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

Isolamento de tokens e multiusuário

No modo streamable-http, o servidor isola os espaços de sessão do navegador por token.

• O cliente MCP envia o token pelo cabeçalho HTTP: Authorization: Bearer <token>
• A extensão do navegador envia o mesmo token pelo campo Token no pop-up
• O token do cliente e o token da extensão devem ser exatamente iguais para que o servidor os roteie para o mesmo contexto de usuário
• Se o token não for preenchido na extensão, o valor padrão __default__ é usado automaticamente
• Se o servidor não tiver --tokens configurado, qualquer token pode se conectar; com --tokens configurado, apenas os tokens da lista de permissões são aceitos
• Em um mesmo computador, você pode fazer diferentes perfis de navegador usarem tokens diferentes para operar em paralelo várias contas da mesma plataforma
• Em computadores diferentes, vários usuários também podem se conectar ao mesmo serviço streamable-http e obter isolamento por meio de tokens diferentes

Configuração padrão

Modo stdio:

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

Se precisar alterar a porta WebSocket da conexão da extensão do navegador, adicione --ws-port em args:

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

Modo streamable-http:

Inicie o serviço primeiro:

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

Se também precisar alterar a porta WebSocket da conexão da extensão do navegador:

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

Depois, configure a conexão do cliente:

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

Se você habilitou o isolamento multiusuário, o cliente deve enviar explicitamente o Bearer token:

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

Nesse caso, o campo Token no pop-up da extensão do navegador também deve ser preenchido com team_alice.

Claude Code

Método 1: adicionar pela linha de comando

# 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

Método 2: arquivo de configuração (recomendado para o modo streamable-http)

Adicione a configuração mcpServers em ~/.claude.json:

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

Observação: ao usar o arquivo de configuração, é necessário iniciar primeiro o serviço cdp-bridge (uvx cdp-bridge@latest --transport streamable-http --port 8000 --ws-port 18765) e, em seguida, reiniciar o 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

Configure em ~/.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

Você pode usar a CLI do OpenClaw para gravar a configuração do 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"}'

A estrutura equivalente de configuração stdio:

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

Observações

• Este projeto requer Python 3.10 ou superior.
• A extensão do navegador tem reconexão automática integrada: após uma falha na primeira conexão, ela continua sondando o serviço WebSocket (a cada ~5 segundos) e restaura a conexão automaticamente quando o serviço MCP é iniciado. Se você vir ERR_CONNECTION_REFUSED, aguarde alguns segundos e a conexão será restabelecida automaticamente.
• A automação de páginas é executada na sua sessão real do navegador; conecte apenas clientes MCP em que você confia.

Agradecimentos

A extensão do navegador e parte do código deste projeto são referenciados e originados do GenericAgent. Agradecemos ao autor do projeto original pelo trabalho de código aberto.