CDP Bridge MCP

CDP Bridge MCP

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. Ele permite que qualquer cliente de modelo de linguagem grande leia abas, digitalize páginas, execute automações, tire capturas de tela e navegue de forma fluida e fácil.

Chinês | English

Vídeo de demonstração

Introdução ao projeto

O CDP Bridge MCP é adequado para cenários em que você precisa que um modelo de linguagem grande opere um navegador real. Diferente da raspagem HTTP sem estado, ele se conecta às páginas do navegador que você já está logado e já abriu, portanto pode reutilizar o estado de login, cookies, estado da página e resultados de renderização do front-end do navegador real.

O CDP Bridge MCP também suporta operação com múltiplos perfis em um único computador e suporta operação multiusuário.

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

Este projeto é escrito e publicado em Python. O MCP suporta dois modos de transporte: stdio e streamable-http.

Vantagens do projeto

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

O Playwright MCP e o Chrome DevTools MCP são ambos muito poderosos, mas são mais voltados para fluxos de trabalho de "teste de automação / protocolo de depuração / nova instância de navegador". O Kimi Bridge tem permissões de funcionalidade limitadas e tende a enviar capturas de tela para modelos de visão para concluir tarefas.

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

• Reutiliza o estado de login real: o CDP Bridge MCP se conecta às abas do navegador que você já abriu e nas quais já está logado. Para muitos sites que exigem estado de conta, não é necessário fazer login novamente ou transferir cookies manualmente.
• Mais adequado para colaboração diária com o navegador: o Playwright é mais adequado 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 capturas 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, 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; 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. Dessa forma, o lado do produto não precisa hospedar o navegador do usuário nem transferir 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 pode concluir leitura, análise e automação na sessão real do navegador autorizada pelo usuário.
• Suporta conexão paralela de múltiplos 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 fazer o Agent operar as páginas reais do navegador de cada uma separadamente.
• Suporta acesso simultâneo de múltiplos usuários em computadores diferentes: extensões de navegador de usuários diferentes, em computadores diferentes, podem se conectar ao mesmo serviço streamable-http, desde que cada um use um token diferente, podendo trabalhar em paralelo sem interferência. Adequado para agentes de atendimento, equipes de operações, nós de coleta de dados ou cenários de colaboração remota.
• Cobre tanto uso pessoal quanto produtos de equipe: usuários individuais podem usar o stdio + 127.0.0.1:18765 padrão para conectar rapidamente ao navegador local; equipes ou desenvolvedores de produtos podem usar o streamable-http + 远端域名 + WebSocket + token para construir um canal de controle do navegador, integrando recursos de navegador real em seus próprios produtos Agent, consoles de atendimento, backends de coleta de dados ou sistemas internos de automação.

Portanto, se seu objetivo é "fazer o modelo controlar um navegador de automação iniciado especificamente", o Playwright MCP é adequado; se seu objetivo é "depurar o Chrome ou operar finamente o protocolo DevTools", o Chrome DevTools MCP é adequado; se seu objetivo é "fazer o modelo ou produto Agent ler e operar as páginas reais do navegador que o usuário está usando atualmente", o CDP Bridge MCP está 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 via Authorization: Bearer <token>.
2. O Token Middleware no lado do servidor é responsável por extrair o token, e o TokenManager é responsável por isolar sessões por token; solicitações MCP e conexões de 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 diferentes perfis de navegador no mesmo computador, podem se conectar simultaneamente.
4. Cada extensão de navegador reporta seu token e as abas abertas ao conectar (modo ext_ws); com base nisso, o servidor isola as páginas reais do navegador de diferentes perfis, contas e usuários.
5. Quando uma ferramenta MCP é chamada (como 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 prioriza o uso de chrome.scripting.executeScript para executar no MAIN world da página; se a página tiver restrições de CSP, ele degrada automaticamente para CDP Runtime.evaluate.
6. Os resultados da execução retornam ao servidor via WebSocket e, em seguida, são retornados ao cliente correspondente pelo protocolo MCP; portanto, é possível operar várias contas da mesma plataforma simultaneamente e também suportar 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 seguintes 12 ferramentas:

Fluxo de operação semântica: primeiro chame browser_observe, selecione o ref do controle no resultado e, em seguida, passe o tab_id e o page_revision do mesmo resultado para browser_act. Após a operação, observe novamente. A versão atual suporta o documento principal da página e Shadow DOM aberto; controles dentro de iframes ainda não estão incluídos nos resultados.

Uso rápido

Abaixo está o fluxo de uso mais rápido com a configuração padrão:

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.

Configure 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 pela primeira vez, aguarde alguns segundos para a reconexão automática.

Uso detalhado

Etapas de instalação

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

Depois disso, você pode usá-lo normalmente. Abaixo estão os detalhes das etapas de instalação acima.

Primeiro uso: após carregar a extensão, a primeira conexão WebSocket pode gerar um erro ERR_CONNECTION_REFUSED, o que é normal. A extensão possui mecanismo interno de reconexão automática (verifica a cada ~5 segundos); quando detecta que o serviço de backend foi iniciado, ela restaura a conexão automaticamente, sem necessidade de 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 (como browser_get_tabs); o serviço WebSocket fica pronto automaticamente quando o serviço MCP é iniciado
4. A extensão do navegador se conecta automaticamente em poucos segundos; depois disso, todas as ferramentas funcionam normalmente

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

As configurações de conexão podem ser alteradas 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, você precisa usar a mesma porta aqui. Se estiver usando um domínio e o serviço usar a porta WebSocket padrão, pode deixar em branco.
• Token: no modo multiusuário 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ê usar token Bearer para acessar o serviço MCP remoto, este campo deve ser preenchido com exatamente o mesmo token do cliente.

Configurando o MCP

Primeiro, confirme se o uv está instalado no computador. O CDP Bridge MCP é iniciado via uvx cdp-bridge@latest.

Dois modos de transporte

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

Parâmetros de inicialização

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

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

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

Avaliação comparativa MCP (V3)

A V3 corrigiu o problema estatístico da V2, que considerava "qualquer texto não vazio retornado pelo modelo como sucesso", e passou a usar regras de aceitação por cenário, dividindo os cenários em comparação central determinística, diagnóstico de 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ório Markdown e JSON estruturado. Por padrão, testa o código-fonte do diretório de trabalho atual e fixa a versão do Playwright MCP para evitar desvio 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, um eval_results.json também é gerado no mesmo diretório; por padrão, o conteúdo completo das ferramentas não é salvo, para evitar gravar abas reais ou privacidade de páginas nos resultados. Para auditoria, você pode adicionar --save-tool-output.

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

A tabela abaixo lista, respectivamente, "tempo mediano / chamadas médias de ferramentas / taxa de sucesso das ferramentas / tokens totais medianos":

Nesta execução, o Playwright teve menor tempo e tokens no cenário de extração simples de conteúdo; o CDP Bridge usou menos chamadas de ferramentas e tokens nos cenários de interação e página externa, com menor tempo mediano e maior taxa de sucesso de ferramentas. Os resultados acima são ponta a ponta sob um modelo, rede e sessão de navegador específicos e não representam conclusões gerais de desempenho; os cenários de estado de login real e abas são itens de diagnóstico e não foram incluídos no ranking central de qualidade 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 da solicitação 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 possa roteá-los 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 tokens da lista de permissões são aceitos
• No mesmo computador, você pode fazer diferentes perfis de navegador usarem tokens diferentes, permitindo operar várias contas da mesma plataforma em paralelo
• Em computadores diferentes, vários usuários também podem se conectar ao mesmo serviço streamable-http e obter isolamento usando tokens diferentes

Configuração padrão

Modo stdio:

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

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

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

Modo streamable-http:

Primeiro, inicie o serviço:

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

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

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

Em seguida, 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 token Bearer:

{
  "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 método de 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 depois 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"}'

Estrutura de configuração stdio equivalente:

{
  "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 possui mecanismo interno de reconexão automática: após falha na primeira conexão, ela continua verificando 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 para a recuperação automática.
• A automação de páginas é executada na sua sessão real do navegador; conecte-se apenas a clientes MCP em que você confia.

Agradecimentos

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