Serveur MCP — piloter Clearcote depuis un agent IA

Connectez Claude Desktop, Cursor ou Cline au serveur MCP de Clearcote et laissez le modèle piloter un navigateur partagé à l’aide de 20 outils. Le persona est défini une seule fois par variables d’environnement, si bien que les outils restent simples : l’agent travaille, l’identité reste cohérente en coulisse.

Configurer votre client MCP

Ajoutez Clearcote à la configuration MCP de votre client (exemple pour Claude Desktop ; Cursor/Cline utilisent le même format) :

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"
      }
    }
  }
}

Les deux méthodes exécutent le même serveur Python : il vous faut donc Python 3.10+. Installez d’abord le serveur avec pip — le lanceur npx réutilise ensuite cette installation — ou mettez "command": "clearcote-mcp" dans la configuration. L’épinglage de mcp maintient le serveur sur la version de la bibliothèque MCP pour laquelle il a été conçu (clearcote-mcp 0.1.0 ne fonctionne pas avec mcp 2.x) :

bash

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

Sans clé de licence, le serveur exécute le build ouvert. Ajoutez CLEARCOTE_LICENSE_KEY à env (ou lancez une fois clearcote login) pour exécuter le dernier build sous licence — Gratuit avec GitHub ou Pro. Les clés gratuites nécessitent le SDK clearcote 0.30.0 ou plus récent, que la commande ci-dessus installe.

Outils

Un seul navigateur partagé, piloté par vingt outils :

Outil	Ce qu’il fait
`navigate`	Charge une URL dans l’onglet courant (renvoie l’URL finale + le titre)
`read_page`	Lit la page actuelle sous forme de texte/markdown
`page_elements`	Liste jusqu’à 200 liens, boutons et champs visibles, chacun avec un sélecteur CSS lorsqu’il en existe un
`click`	Clique sur un élément
`fill_field`	Saisit du texte dans un input / textarea
`press_key`	Appuie sur une touche (Enter, Tab, …)
`wait_for`	Attend qu’un sélecteur apparaisse
`screenshot_page`	Capture d’écran PNG de la page entière, enregistrée dans le dossier sandbox (renvoie le chemin)
`list_tabs / new_tab / close_tab`	Gère les onglets
`save_profile / load_profile`	Enregistre les cookies + le stockage dans un fichier nommé de la sandbox, puis restaure les cookies plus tard — connectez-vous une fois, réutilisez la session
`get_egress_info`	L’IP publique et le persona actif
`get_cdp_endpoint`	Renvoie l’URL CDP pour un client brut

…ainsi que get_page_html, evaluate_js, current_page, get_cookies (lecture seule) et save_page_pdf (headless uniquement). L’agent lit la page, décide et agit — le tout via une seule instance Clearcote, cohérente avec son persona.

Le persona par variables d’environnement

Les bases du persona se règlent avec les variables d’environnement CLEARCOTE_* : le modèle n’a jamais à se soucier de l’identité. Pour les autres options d’empreinte, utilisez directement le SDK.

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

Les proxys authentifiés nécessitent le build sous licence ; le build ouvert ne peut pas transmettre les identifiants du proxy au navigateur.

Garde-fous

Les appels d’outils dont l’URL pointe vers localhost, un réseau privé ou un endpoint de métadonnées cloud sont refusés. C’est une protection contre les erreurs, pas une sandbox : un script exécuté avec evaluate_js et les liens que suit la page peuvent toujours atteindre ces adresses. Définissez CLEARCOTE_ALLOW_PRIVATE_EGRESS=1 pour les autoriser (par exemple pour tester un serveur de développement local).
Les captures d’écran, les PDF et les sessions enregistrées sont écrits dans <temp>/clearcote-mcp (CLEARCOTE_MCP_WRITE_DIR pour changer d’emplacement).
Chaque appel d’outil expire au bout de 90 secondes (CLEARCOTE_MCP_TOOL_TIMEOUT).
Le navigateur démarre dès que votre client MCP lance le serveur. Avec une clé de l’offre Gratuit avec GitHub, il occupe immédiatement votre unique place de navigateur ; définissez CLEARCOTE_MCP_PREWARM=0 pour ne le démarrer qu’au premier appel d’outil.

Le serveur MCP lance le navigateur directement, sans le flag d’automatisation de Playwright : navigator.webdriver reste donc à false, et le moteur tient les effets de bord habituels de CDP à l’écart de la page. Deux façons d’automatiser : un LLM à l’extérieur du navigateur (ce serveur MCP) ou l’agent IA intégré au navigateur, qui s’exécute dans le processus.

Besoin d’un endpoint brut plutôt que de MCP ? Consultez Déploiement & Docker.