Servidor MCP — controle o Clearcote a partir de um agente de IA

Aponte o Claude Desktop, o Cursor ou o Cline para o servidor MCP do Clearcote e deixe o modelo controlar um único navegador compartilhado por meio de 20 ferramentas. A persona é definida uma só vez pelas variáveis de ambiente, então o conjunto de ferramentas fica enxuto — o agente trabalha, e a identidade continua coerente por baixo.

Configure seu cliente MCP

Adicione o Clearcote à configuração MCP do seu cliente (o exemplo é do Claude Desktop; Cursor/Cline usam o mesmo formato):

json

{
  "mcpServers": {
    "clearcote": {
      "command": "npx",
      "args": ["-y", "clearcote-mcp"],
      "env": {
        "CLEARCOTE_FINGERPRINT": "acct-1",
        "CLEARCOTE_PLATFORM": "windows",
        "CLEARCOTE_PROXY": "http://host:8080",
        "CLEARCOTE_GEOIP": "1"
      }
    }
  }
}

As duas formas rodam o mesmo servidor Python, então você precisa do Python 3.10+. Instale com o pip primeiro — o launcher npx reaproveita essa instalação — ou use "command": "clearcote-mcp" na configuração. O pin do mcp mantém o servidor na versão da biblioteca MCP para a qual ele foi feito (o clearcote-mcp 0.1.0 não roda com o mcp 2.x):

bash

pip install -U clearcote clearcote-mcp "mcp[cli]<2"

Sem chave de licença, o servidor roda o build aberto. Adicione CLEARCOTE_LICENSE_KEY ao env (ou rode clearcote login uma vez) para usar o build licenciado mais recente — Grátis com GitHub ou Pro. Chaves gratuitas precisam do SDK clearcote 0.30.0 ou mais recente, que o comando acima instala.

Ferramentas

Um único navegador compartilhado é controlado por vinte ferramentas:

Ferramenta	O que faz
`navigate`	Carrega uma URL na aba atual (retorna a URL final + o título)
`read_page`	Lê o estado atual da página como texto/markdown
`page_elements`	Lista até 200 links, botões e campos visíveis, cada um com um seletor CSS quando houver
`click`	Clica em um elemento
`fill_field`	Digita em um input / textarea
`press_key`	Pressiona uma tecla (Enter, Tab, …)
`wait_for`	Espera um seletor aparecer
`screenshot_page`	Screenshot em PNG da página inteira, salvo na pasta da sandbox (retorna o caminho)
`list_tabs / new_tab / close_tab`	Gerencia as abas
`save_profile / load_profile`	Salva cookies + storage em um arquivo nomeado na sandbox e restaura os cookies depois — faça login uma vez e reaproveite a sessão
`get_egress_info`	O IP público e a persona ativa
`get_cdp_endpoint`	Retorna a URL do CDP para um cliente direto

…além de get_page_html, evaluate_js, current_page, get_cookies (somente leitura) e save_page_pdf (somente headless). O agente lê a página, decide e age — tudo por meio de uma única instância do Clearcote, com a persona sempre consistente.

Persona pelas variáveis de ambiente

O básico da persona é definido com as variáveis de ambiente CLEARCOTE_*, então o modelo nunca precisa pensar em identidade. Para o restante das opções de fingerprint, use o SDK diretamente.

bash

CLEARCOTE_FINGERPRINT=acct-1          # seed -> stable identity
CLEARCOTE_PLATFORM=windows            # windows | linux | macos | android
CLEARCOTE_BRAND=Edge                  # Chrome (default) | Edge | Opera | Vivaldi
CLEARCOTE_ACCEPT_LANGUAGE=en-US
CLEARCOTE_TIMEZONE=America/New_York
CLEARCOTE_PROXY=http://user:pass@host:8080
CLEARCOTE_GEOIP=1                     # timezone + language + WebRTC follow the proxy exit
CLEARCOTE_HEADLESS=0                  # show the window (default: headless)
CLEARCOTE_LICENSE_KEY=cc_lic_...      # optional -> the latest licensed build

Proxies autenticados exigem o build licenciado; o build aberto não consegue repassar as credenciais do proxy para o navegador.

Proteções

Chamadas de ferramenta cuja URL aponta para localhost, para uma rede privada ou para um endpoint de metadados de nuvem são recusadas. Isso é uma proteção contra erros, não uma sandbox: scripts executados com evaluate_js e links que a página segue ainda conseguem chegar a esses endereços. Defina CLEARCOTE_ALLOW_PRIVATE_EGRESS=1 para liberá-los (por exemplo, para testar um servidor de desenvolvimento local).
Screenshots, PDFs e sessões salvas são gravados em <temp>/clearcote-mcp (CLEARCOTE_MCP_WRITE_DIR muda o local).
Cada chamada de ferramenta tem timeout de 90 segundos (CLEARCOTE_MCP_TOOL_TIMEOUT).
O navegador inicia assim que o seu cliente MCP sobe o servidor. Com uma chave Grátis com GitHub, isso já ocupa a sua única vaga de navegador; defina CLEARCOTE_MCP_PREWARM=0 para que ele só inicie na primeira chamada de ferramenta.

O servidor MCP inicia o navegador diretamente, sem a flag de automação do Playwright, então navigator.webdriver continua false e o motor mantém os efeitos colaterais habituais do CDP longe da página. Há duas formas de automatizar: um LLM fora do navegador (este servidor MCP) ou o agente de IA dentro do navegador, que roda no próprio processo.

Precisa de um endpoint direto em vez de MCP? Veja Deploy & Docker.