Guide Playwright MCP : donner à Claude, Codex et Cursor le contrôle du navigateur

Vous ajoutez [mcp_servers.playwright] dans .codex/config.toml, vous lancez codex, et le navigateur s’ouvre bien. Pourtant l’IA n’appelle pas les outils navigateur. Ou bien elle ouvre la page, mais ne trouve pas le bouton dans la barre de navigation. Ce guide détaille les configurations complètes pour Claude Code, Codex et Cursor, la checklist de première validation, et les permissions navigateur à ne pas confier trop vite à une IA.

---

Qu’est-ce que Playwright MCP

Playwright MCP est le MCP server maintenu par Microsoft qui expose l’automatisation navigateur de Playwright aux outils de codage IA via le Model Context Protocol. Son principe central n’est pas la reconnaissance d’images. Il s’appuie sur l’accessibility tree : l’IA reçoit une vue structurée de la page et peut y repérer boutons, liens, champs de saisie et autres éléments interactifs.

Capacités principales et liste d’outils

Playwright MCP couvre les principaux scénarios d’automatisation navigateur :

• Navigation : ouvrir une URL, revenir en arrière, avancer, recharger
• Clic et saisie : cliquer sur des éléments, remplir des formulaires, utiliser le clavier
• Captures et snapshots : prendre des captures d’écran et obtenir un accessibility snapshot
• Dialogues et onglets : gérer alert/confirm/prompt et administrer plusieurs onglets
• Réseau et console : intercepter les requêtes réseau et capturer les console logs
• État de stockage : sauvegarder et restaurer cookies, localStorage et sessionStorage

Ces capacités lui permettent de traiter aussi bien un clic simple qu’une soumission de formulaire plus complexe.

Différence avec Playwright CLI/SKILLS

Le README Microsoft distingue clairement deux approches :

• La voie MCP : adaptée aux cas qui exigent un état persistant, une introspection riche et un contexte navigateur continu, par exemple l’automatisation exploratoire, les tests auto-réparateurs ou les tâches longues. Le coût est que les tool schemas et l’accessibility tree entrent dans le contexte et consomment des tokens.
• La voie CLI + SKILLS : adaptée aux workflows de code à fort débit, avec une empreinte de contexte plus faible, mais qui vous oblige à appeler Playwright via la ligne de commande ou des scripts.

Si vous utilisez déjà Claude Code, Codex, Cursor ou un autre outil de codage IA compatible MCP, Playwright MCP est le chemin le plus direct pour ajouter des outils navigateur à votre workflow.

Différence avec Browser Use

Browser Use est un agent loop Python. Vous écrivez du code Python qui appelle son API, puis l’agent décide des actions navigateur à partir d’un prompt. Playwright MCP est différent : il ne fournit pas la boucle agent. Il fournit la couche d’outils navigateur, et votre MCP client existant, Claude Code, Codex ou Cursor, décide quand appeler ces outils.

Si vous êtes développeur Python et voulez démarrer rapidement avec un Browser Agent, commencez par le tutoriel Browser Use qui ouvre une page, clique sur des boutons et extrait des informations. Si vous travaillez déjà dans un MCP client et voulez ajouter le navigateur à cet environnement, cet article vous aide à installer, valider et sécuriser Playwright MCP.

Ce n’est pas un remplacement du framework de test

Playwright MCP ne remplace pas le framework de test Playwright. Il convient à l’automatisation exploratoire et aux validations frontend, mais une suite E2E stable doit toujours être écrite avec le framework de test Playwright. Un test a besoin de déterminisme, de reproductibilité et de maintenabilité ; les actions navigateur pilotées par l’IA ne sont pas entièrement contrôlables. Si les tests en mode navigateur vous intéressent, voyez aussi Vitest Browser Mode.

---

Configurer Playwright MCP dans Claude Code

Prérequis

Claude Code nécessite Node.js 18+ pour exécuter Playwright MCP. Vérifiez votre version de Node :

node --version

Si elle est inférieure à 18, mettez d’abord Node.js à niveau.

Commande d’ajout

Claude Code propose une commande dédiée à la gestion MCP. Exécutez-la à la racine du projet :

claude mcp add playwright npx @playwright/mcp@latest

Cette commande enregistre le Playwright MCP server dans Claude Code. Utilisez @playwright/mcp@latest et ne reprenez pas les anciens noms de packages communautaires comme @executeautomation/playwright-mcp-server.

Configuration projet .mcp.json

Si vous voulez partager la configuration Playwright MCP avec l’équipe, créez un fichier .mcp.json à la racine du projet :

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "BROWSER_PATH": "/usr/bin/chromium"
      }
    }
  }
}

Quand Claude Code détecte un .mcp.json au niveau projet, il demande une approbation. C’est une protection contre l’ajout silencieux d’un MCP server non fiable par un projet.

Expansion des variables d’environnement

.mcp.json prend en charge l’expansion des variables d’environnement pour les chemins propres à une machine et les valeurs sensibles :

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "HOME": "${env:HOME}",
        "STORAGE_STATE_PATH": "${env:STORAGE_STATE_PATH}"
      }
    }
  }
}

Tool Search et gestion des tokens de sortie

Claude Code active MCP Tool Search par défaut. Les outils sont chargés à la demande, ce qui réduit l’usage du contexte. Quand la sortie MCP est volumineuse, Claude Code applique aussi une gestion des tokens, avec un maximum par défaut de 25 000 tokens. Si l’IA n’utilise pas les outils navigateur, vérifiez :

1. Que le MCP server démarre correctement dans les logs Claude Code
2. Que Tool Search est activé, ce qui est le cas par défaut dans Claude Code
3. Que Node.js est en version 18 ou supérieure

---

Configurer Playwright MCP dans Codex

OpenAI Codex prend en charge les MCP servers dans la CLI et l’IDE extension, mais sa configuration diffère de celle de Claude Code.

Commande d’ajout

La CLI Codex fournit une commande de gestion MCP :

codex mcp add playwright -- npx @playwright/mcp@latest

Dans Codex, -- sépare le nom du server de la commande réelle.

Emplacement du fichier de configuration

La configuration MCP de Codex est stockée dans config.toml. Deux emplacements sont possibles :

• Niveau utilisateur : ~/.codex/config.toml (effet global)
• Niveau projet : .codex/config.toml à la racine du projet (effet limité au projet)

La CLI et l’IDE extension partagent cette configuration.

Extrait config.toml

Pour une configuration manuelle, ajoutez ceci dans config.toml :

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

Si vous devez transmettre des variables d’environnement ou ajuster l’approbation des outils, ajoutez :

env_vars = ["HOME", "STORAGE_STATE_PATH"]
approval_mode = "prompt"

Modes d’approbation des outils

Codex fournit trois modes d’approbation :

• approval_mode = "allow" : exécuter automatiquement tous les appels d’outils
• approval_mode = "prompt" : demander confirmation avant chaque appel d’outil
• approval_mode = "deny" : refuser tous les appels d’outils

Pour les outils Playwright MCP à haut risque, comme browser_run_code_unsafe, utilisez :

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
disabled_tools = ["browser_run_code_unsafe"]
approval_mode = "prompt"

Cela empêche l’exécution automatique des outils à haut risque et garde les opérations sensibles derrière une approbation humaine.

Prise en charge des HTTP servers

Codex prend en charge deux types de MCP server :

• STDIO server : communication par processus local, adaptée aux outils qui doivent accéder au système local, comme Playwright MCP
• HTTP server : prise en charge des bearer tokens et de l’authentification OAuth

Playwright MCP utilise STDIO. La configuration HTTP n’est donc pas nécessaire pour le chemin standard.

---

Configurer Playwright MCP dans Cursor

La configuration MCP de Cursor passe par la Settings UI, contrairement aux approches en ligne de commande de Claude Code et Codex.

Étapes dans l’interface

D’après la documentation officielle Playwright, la configuration Cursor se fait ainsi :

1. Ouvrez Cursor Settings (Cmd+, ou via le menu Settings)
2. Allez dans la page MCP (Settings -> MCP)
3. Cliquez sur “Add new MCP Server”
4. Renseignez la configuration :
   • Server name : playwright
   • Command type : npx
   • Command : @playwright/mcp@latest

Paramètres standard

La configuration MCP server de Cursor peut utiliser les paramètres standard de Playwright MCP :

• --headless : mode sans fenêtre visible ; en développement, le mode headed est plus facile à observer
• --browser : choix du navigateur (chrome/firefox/webkit/msedge)
• --output-dir : chemin du répertoire de sortie
• --storage-state : chemin du fichier d’état de connexion

La liste complète apparaît plus bas dans le tableau des paramètres standard.

Référence de configuration

La documentation MCP de Cursor est disponible dans les docs Cursor. Pour les détails propres à Playwright MCP, prenez la documentation Playwright et le README Microsoft comme référence, et vérifiez que vous utilisez bien le package officiel @playwright/mcp@latest.

---

Tableau des paramètres de configuration standard

Playwright MCP fournit plusieurs paramètres pour contrôler le comportement du navigateur, les limites de sécurité et la gestion des sorties.

Paramètre	Rôle	Valeur par défaut	Note de sécurité
--headless	Mode sans fenêtre navigateur visible	false (headed)	En développement, préférez headed pour observer les actions navigateur
--browser	Choisir le type de navigateur	chrome	Options : chrome, firefox, webkit, msedge
--allowed-origins	Liste des origins autorisées	Sans limite	Ce n’est pas une limite de sécurité ; n’affecte pas les redirects et ne protège pas seul les sites sensibles
--blocked-origins	Liste des origins bloquées	Aucune	Ce n’est pas une limite de sécurité, même réserve
--isolated	Mode isolé, chaque session utilise un profile indépendant	false	Recommandé pour les clients concurrents ou les projets multiples
--storage-state	Chemin d’un fichier d’état de connexion	Aucun	Sauvegarde cookies et localStorage ; prudence avec de vrais comptes
--output-dir	Répertoire de sortie pour captures, logs, etc.	Aucun	Spécifiez un chemin pour retrouver facilement les résultats
--save-session	Sauvegarder l’état de session	false	À utiliser avec un persistent profile
--snapshot-mode	Mode d’accessibility snapshot	default	Contrôle le niveau de détail du snapshot
--allow-unrestricted-file-access	Autoriser l’accès fichier sans restriction	false	Haut risque, à activer avec prudence
--secrets	Configuration de secrets via variables d’environnement ou fichiers	Aucun	Sert à gérer les informations sensibles

Rappel clé : la documentation officielle indique que --allowed-origins et --blocked-origins ne sont pas des limites de sécurité et n’affectent pas les redirects. Si vous devez restreindre les sites accessibles à l’IA, ne comptez pas uniquement sur ces paramètres.

---

Comparatif des trois modes de profile

Playwright MCP prend en charge trois modes de profile, qui influencent la sauvegarde de l’état de connexion, la concurrence et les limites de sécurité.

Mode	État de connexion sauvegardé	Chemin du profile	Concurrence	Cas d’usage	Recommandation de sécurité
persistent	Sauvegarde cookies, localStorage, etc.	macOS: ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}	Un profile ne peut être utilisé que par une browser instance à la fois	Tâches longues où l’IA doit conserver l’état de connexion	Éviter les vrais comptes, commencer par un compte de test
isolated	Ne sauvegarde rien, chaque session est indépendante	Répertoire temporaire, nettoyé automatiquement à chaque session	Compatible avec des clients concurrents ou plusieurs projets	Tests, exploration, tâches sans état de connexion	Choix recommandé par défaut en production
browser extension	Sauvegarde selon le navigateur	Répertoire de l’extension navigateur	Dépend du navigateur	Connexion à une session navigateur existante	Usage avancé, nécessitant de comprendre le modèle de sécurité des extensions

Limites du persistent profile

Un persistent profile ne peut être utilisé que par une seule browser instance à la fois. Si vous devez utiliser plusieurs clients ou plusieurs projets avec Playwright MCP en parallèle, vous devez :

• Utiliser le mode --isolated
• Ou configurer un --user-data-dir différent pour chaque client

Exemple de chemin persistent profile sur macOS :

~/Library/Caches/ms-playwright/mcp-chrome-a1b2c3d4

Le segment {workspace-hash} est généré automatiquement à partir du projet. Des projets différents utilisent donc des profiles différents.

État de connexion et limites de sécurité

Un persistent profile sauvegarde cookies, localStorage et sessionStorage. L’IA peut accéder à l’état de connexion stocké dans le navigateur. Si vous utilisez un vrai compte, elle peut potentiellement accéder à vos données personnelles, informations de paiement et paramètres de compte.

Pratiques recommandées :

• En production, utiliser --isolated pour ne pas conserver l’état de connexion
• Si l’IA doit manipuler un état connecté, utiliser un compte de test plutôt qu’un vrai compte
• Ne pas laisser l’IA se connecter automatiquement à votre vrai compte ni ouvrir des pages de paiement

La gestion détaillée de l’état de connexion fera l’objet d’un article ultérieur sur l’état de connexion des navigateurs IA. Ici, on pose seulement la limite.

---

Alerte de sécurité sur browser_run_code_unsafe

Alerte de sécurité : browser_run_code_unsafe permet d’exécuter des scripts Playwright arbitraires. La documentation officielle le marque comme RCE-equivalent. Ne l’activez que pour des MCP clients entièrement fiables. En production, désactivez-le ou imposez une approbation humaine via approval_mode: prompt dans Codex.

Playwright MCP fournit un outil à haut risque : browser_run_code_unsafe. Il peut exécuter n’importe quel script Playwright dans le contexte du navigateur. Le danger est direct :

• Si le MCP client est compromis ou si le comportement de l’IA n’est pas contrôlé, un attaquant peut exécuter du code arbitraire via cet outil
• L’IA peut lire toutes les données du navigateur, y compris cookies, localStorage, sessionStorage et données personnelles de comptes connectés
• Si le navigateur consulte une page de paiement ou de paramètres de compte, l’IA peut lire et exfiltrer des données sensibles

Recommandations de configuration de sécurité

En production :

1. Désactiver browser_run_code_unsafe :

   Ajoutez ceci dans ~/.codex/config.toml de Codex :

   [mcp_servers.playwright]
   command = "npx"
   args = ["@playwright/mcp@latest"]
   disabled_tools = ["browser_run_code_unsafe"]

2. Ou définir un mode d’approbation :

   [mcp_servers.playwright]
   command = "npx"
   args = ["@playwright/mcp@latest"]
   approval_mode = "prompt"

   Ainsi, Codex affiche une confirmation avant chaque appel à browser_run_code_unsafe, et vous devez l’approuver manuellement.

En développement :

Si vous devez vraiment utiliser browser_run_code_unsafe :

• Activez-le uniquement en local, pas en production ni avec de vrais comptes
• Assurez-vous de comprendre entièrement le script exécuté
• Ne laissez pas l’IA générer puis exécuter automatiquement le script ; écrivez vous-même le script et demandez à l’IA d’exécuter ce script connu

Déconseillé aux débutants

Si vous découvrez Playwright MCP, ne commencez pas par browser_run_code_unsafe. Utilisez d’abord les autres outils plus sûrs de Playwright MCP, comme browser_click, browser_navigate ou browser_screenshot. Leurs limites sont plus claires et ils n’exécutent pas de code arbitraire.

---

Checklist de sécurité pour MCP Tools

Le protocole MCP permet à l’IA d’appeler des outils externes, mais “brancher MCP” ne signifie pas “laisser l’IA tout faire automatiquement”. Il faut contrôler les limites de sécurité côté client et côté serveur.

Recommandations côté client

1. Demander confirmation pour les actions sensibles : avant browser_run_code_unsafe, l’accès à une page de paiement, la modification de paramètres de compte ou la suppression de données, demandez une confirmation utilisateur. Ne laissez pas l’IA exécuter automatiquement ces opérations à haut risque.

2. Afficher les tool inputs avant l’appel : l’utilisateur doit voir les paramètres exacts que l’IA va utiliser. Par exemple, si l’IA veut cliquer sur un bouton, affichez le selector ou les coordonnées et confirmez qu’ils sont corrects.

3. Prévenir les fuites de données malveillantes : inspectez les sorties d’outils pour éviter que des informations sensibles, mots de passe, tokens ou données personnelles, soient lues par l’IA puis transmises ailleurs. Si un outil retourne des données sensibles, ne laissez pas l’IA les écrire dans des logs ni les envoyer à un server externe.

4. Définir un timeout : une action navigateur peut rester bloquée, consommer des ressources ou bloquer d’autres tâches. Définissez un timeout raisonnable pour chaque appel d’outil, par exemple 30 secondes, et annulez automatiquement en cas de dépassement.

5. Journaliser le tool usage : conservez un journal d’opérations pour l’audit et le diagnostic. Il doit contenir le nom de l’outil, l’heure d’appel, les paramètres d’entrée, le résultat et l’enregistrement de l’approbation utilisateur.

6. Vérifier les tool results : contrôlez que les captures d’écran, console logs et requêtes réseau correspondent au résultat attendu. Si l’IA annonce “clic réussi” mais que la capture ne montre aucun changement, il faut diagnostiquer.

Recommandations côté serveur

Si vous développez vous-même un MCP server (Playwright MCP est le server officiel, vous n’avez pas besoin de le réécrire), suivez ces recommandations :

1. Valider les entrées : validez URL, sélecteurs et contenus saisis pour éviter les injections. Ne laissez pas l’IA transmettre une URL malveillante ou un XSS payload sans contrôle.

2. Contrôler l’accès : limitez les domaines, chemins de fichiers et capacités navigateur accessibles. Par exemple, interdisez l’accès aux IP internes ou aux chemins sensibles.

3. Limiter le débit : empêchez l’IA d’appeler les outils si souvent qu’elle épuise les ressources ou se fasse bloquer par le site cible. Définissez une limite raisonnable, par exemple 10 appels par minute.

4. Nettoyer les sorties : retirez les informations sensibles avant de les renvoyer à l’IA. Par exemple, ne renvoyez pas une chaîne complète de cookies si une valeur dérivée suffit.

---

Première tâche de validation et checklist d’acceptation

Une fois la configuration terminée, utilisez une tâche simple pour vérifier que Playwright MCP est bien connecté.

Exemple de tâche

Demandez à l’IA d’ouvrir la preview locale http://localhost:4321, de cliquer sur le menu de navigation, de prendre une capture d’écran et de signaler les console errors.

Étapes :

1. Vérifiez que Playwright MCP est ajouté à votre client, que ce soit Claude Code, Codex ou Cursor

2. Démarrez le serveur de développement local, Astro ou Next.js par exemple, et vérifiez que http://localhost:4321 est accessible

3. Saisissez ce prompt dans Claude Code/Codex/Cursor :

   Ouvre http://localhost:4321, clique sur "Articles" dans le menu de navigation, prends une capture d'écran et indique si la page contient des console errors.

4. Observez si l’IA appelle les outils navigateur, si le navigateur démarre et si la page s’ouvre

Checklist d’acceptation

Vérification	Résultat attendu	Comment confirmer
Le navigateur démarre	Une fenêtre s’ouvre en headed mode, ou le processus démarre en headless	Observer l’UI ou le gestionnaire de processus
Le MCP server est connecté	Les logs du client affichent “Connected to MCP server”	Consulter les logs du client
L’accessibility snapshot revient	L’IA trouve le menu de navigation et clique	La sortie de l’IA contient la description de l’action de clic
L’appel d’outil demande une approbation	Selon la configuration, Codex peut afficher une boîte d’approbation	Observer si le client demande une confirmation
Les sorties et logs sont traçables	Captures d’écran, console logs et sorties associées se trouvent dans --output-dir	Vérifier le répertoire configuré

Diagnostic des échecs

L’IA n’appelle pas les outils navigateur :

• Vérifiez que le MCP server a été correctement ajouté dans les logs du client
• Vérifiez que le client prend en charge MCP Tool Search ; Claude Code l’active par défaut
• Vérifiez que Node.js est en version 18 ou supérieure

Le navigateur s’ouvre, mais le bouton est introuvable :

• Playwright MCP agit sur l’accessibility tree, pas sur une image. Si la page manque de labels sémantiques ou d’attributs ARIA, l’IA peut ne pas l’identifier
• Inspectez la structure HTML et assurez-vous que le bouton a un label accessible ou un role
• Ou ajustez le paramètre --snapshot-mode pour modifier le niveau de détail du snapshot

Le navigateur démarre puis se ferme immédiatement :

• Il peut s’agir du mode headless ou d’un script terminé
• Consultez les logs du client pour confirmer que le navigateur a démarré et s’est fermé normalement
• En mode headed, la fenêtre devrait rester ouverte jusqu’au rapport final de l’IA

---

Arbitrer entre Playwright MCP et CLI/SKILLS

Le README Microsoft indique que, pour les coding agents dans des workflows de code à fort débit, CLI + SKILLS peut être plus adapté, car MCP injecte les tool schemas et l’accessibility tree dans le contexte et consomme des tokens. MCP convient mieux aux cas qui nécessitent un état persistant, une introspection riche et un contexte navigateur continu pour de l’automatisation exploratoire, des tests auto-réparateurs ou des tâches longues.

Tableau de comparaison par scénario

Scénario	Recommander Playwright MCP	Recommander Playwright CLI + SKILLS
Automatisation exploratoire, tests auto-réparateurs	Oui, adapté	Non, peu adapté
Tâches longues nécessitant un contexte navigateur persistant	Oui, adapté	Non, peu adapté
Workflows de code à fort débit	Non, le contexte est plus coûteux	Oui, adapté
Besoin d’une empreinte de contexte minimale	Non, peu adapté	Oui, adapté
Vous utilisez déjà un MCP client comme Claude Code/Codex/Cursor	Oui, adapté	Non, peu adapté

Cet article ne détaille pas l’usage de SKILLS. Un article ultérieur couvrira la validation navigateur avec Codex en pratique.

---

Résumé et prochaines étapes

Cet article a couvert la configuration Playwright MCP pour Claude Code, Codex et Cursor, la première checklist de validation et les limites de sécurité : risque RCE de browser_run_code_unsafe, persistance de l’état de connexion dans les modes de profile, et le fait que --allowed-origins n’est pas une limite de sécurité.

Résumé des différences de configuration

• Claude Code : utiliser claude mcp add ou un .mcp.json au niveau projet ; Tool Search est activé par défaut
• Codex : utiliser codex mcp add ou config.toml ; approval_mode permet de contrôler les outils à haut risque
• Cursor : configurer via la Settings UI, avec un parcours différent des deux autres

Prochaines lectures conseillées

• Besoin d’un comparatif d’outils : lisez Browser Use vs Stagehand vs Playwright MCP, guide 2026 de choix des outils navigateur IA
• Besoin de gérer l’état de connexion : lisez Gestion de l’état de connexion des navigateurs IA
• Besoin de tests frontend : lisez Tests et validation frontend avec Playwright
• Besoin de validation navigateur dans Codex : lisez Validation navigateur Codex en pratique
• Besoin d’infrastructure hébergée : lisez Infrastructure navigateur hébergée
• Besoin de sécurité et d’approbation : lisez Sécurité des navigateurs IA et conception des approvals

Si vous venez de configurer Playwright MCP, lancez d’abord la tâche de validation sur localhost:4321. Vérifiez que le navigateur démarre, que l’IA appelle les outils et que les captures d’écran sont écrites dans le répertoire configuré. En cas de problème, suivez la FAQ et vérifiez la version de Node.js, les logs du client et l’état de connexion du MCP server.