Guida pratica a Playwright MCP: far controllare il browser a Claude, Codex e Cursor

Aggiungi [mcp_servers.playwright] in .codex/config.toml, avvii codex e il browser si apre davvero. Eppure l’IA non chiama gli strumenti browser, oppure apre la pagina ma non trova il pulsante nella barra di navigazione. Questa guida mostra la configurazione completa per Claude Code, Codex e Cursor, la checklist per la prima verifica e i permessi browser che non dovresti consegnare all’IA con leggerezza.

---

Che cos’è Playwright MCP

Playwright MCP è l’MCP server mantenuto ufficialmente da Microsoft che espone l’automazione browser di Playwright agli strumenti di coding con IA tramite Model Context Protocol. Il suo principio non è il riconoscimento degli screenshot. Lavora sull’accessibility tree e offre all’IA una vista strutturata della pagina, così può trovare pulsanti, link, campi di input e altri elementi interattivi.

Funzionalità principali e lista degli strumenti

Playwright MCP copre i principali scenari di automazione browser:

• Navigazione: aprire URL, andare avanti e indietro, aggiornare
• Clic e input: cliccare elementi, compilare form, usare la tastiera
• Screenshot e snapshot: catturare screenshot della pagina e ottenere accessibility snapshot
• Dialoghi e tab: gestire alert/confirm/prompt e amministrare più tab
• Rete e console: intercettare richieste di rete e catturare console log
• Stato di storage: salvare e ripristinare cookies, localStorage e sessionStorage

Queste capacità gli permettono di gestire sia un semplice clic sia un flusso complesso di invio form.

Differenza rispetto a Playwright CLI/SKILLS

Il README ufficiale Microsoft esplicita il compromesso tra due strade:

• Strada MCP: adatta quando servono stato persistente, introspection ricca e contesto browser continuo, per esempio automazione esplorativa, test auto-riparanti o task lunghi. Il costo è che tool schema e accessibility tree entrano nel contesto e consumano token.
• Strada CLI + SKILLS: adatta a workflow di codice ad alto throughput, con minore consumo di contesto, ma richiede di chiamare Playwright da riga di comando o script.

Se usi già uno strumento di coding IA con supporto MCP, come Claude Code, Codex o Cursor, Playwright MCP è il modo più diretto per inserire strumenti browser nel workflow esistente.

Differenza rispetto a Browser Use

Browser Use è un agent loop Python. Scrivi codice Python contro la sua API, poi l’agent decide le azioni browser in base al prompt. Playwright MCP è diverso: non fornisce l’agent loop. Fornisce il livello di strumenti browser, mentre il tuo MCP client esistente, Claude Code, Codex o Cursor, decide quando chiamarli.

Se sei uno sviluppatore Python e vuoi iniziare rapidamente con Browser Agent, puoi partire dal tutorial Browser Use per aprire pagine, cliccare pulsanti ed estrarre informazioni. Se lavori già dentro un MCP client e vuoi collegare capacità browser a quello strumento, questa guida ti aiuta a installare, validare e mettere in sicurezza Playwright MCP.

Non è un sostituto del framework di test

Playwright MCP non è un sostituto del framework di test Playwright. È adatto ad automazione esplorativa e verifiche frontend, ma una suite E2E stabile deve comunque essere scritta con script di test Playwright. I test richiedono determinismo, ripetibilità e manutenibilità; le azioni browser guidate dall’IA non sono pienamente controllabili. Se ti interessa il testing in modalità browser, vedi anche Vitest Browser Mode.

---

Configurare Playwright MCP in Claude Code

Prerequisiti

Claude Code richiede Node.js 18+ per eseguire Playwright MCP. Controlla la versione di Node:

node --version

Se è inferiore a 18, aggiorna prima Node.js.

Comando di aggiunta

Claude Code offre un comando dedicato alla gestione MCP. Eseguilo nella root del progetto:

claude mcp add playwright npx @playwright/mcp@latest

Questo comando registra il Playwright MCP server in Claude Code. Usa @playwright/mcp@latest; non copiare vecchi nomi di pacchetti community come @executeautomation/playwright-mcp-server.

Configurazione di progetto .mcp.json

Se vuoi condividere la configurazione Playwright MCP con il team, puoi creare .mcp.json nella root del progetto:

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

Quando Claude Code trova un .mcp.json a livello di progetto, chiede approvazione. È una protezione contro l’introduzione silenziosa di un MCP server non affidabile.

Espansione delle variabili d’ambiente

.mcp.json supporta l’espansione delle variabili d’ambiente per percorsi specifici della macchina e valori sensibili:

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

Tool Search e gestione dei token di output

Claude Code abilita MCP Tool Search di default. Gli strumenti vengono caricati in modo differito, riducendo l’uso del contesto. Quando l’output MCP è grande, Claude Code applica anche una gestione dei token, con massimo predefinito di 25.000 tokens. Se l’IA non usa gli strumenti browser, controlla:

1. Che l’MCP server sia avviato correttamente nei log di Claude Code
2. Che Tool Search sia attivo, come accade di default in Claude Code
3. Che Node.js sia alla versione 18 o superiore

---

Configurare Playwright MCP in Codex

OpenAI Codex supporta MCP servers sia nella CLI sia nell’IDE extension, ma la configurazione è diversa da Claude Code.

Comando di aggiunta

La CLI di Codex offre un comando di gestione MCP:

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

In Codex, -- separa il nome del server dal comando effettivo.

Posizione del file di configurazione

La configurazione MCP di Codex è salvata in config.toml. Ci sono due posizioni:

• Livello utente: ~/.codex/config.toml, con effetto globale
• Livello progetto: .codex/config.toml nella root del progetto, valido solo per quel progetto

CLI e IDE extension condividono questa configurazione.

Frammento config.toml

Per configurarlo manualmente, aggiungi questo a config.toml:

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

Se devi passare variabili d’ambiente o regolare l’approvazione degli strumenti, aggiungi:

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

Modalità di approvazione degli strumenti

Codex offre tre modalità di approvazione:

• approval_mode = "allow": esegue automaticamente tutte le chiamate agli strumenti
• approval_mode = "prompt": chiede conferma all’utente prima di ogni chiamata
• approval_mode = "deny": nega tutte le chiamate agli strumenti

Per strumenti Playwright MCP ad alto rischio, come browser_run_code_unsafe, conviene usare:

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

Così eviti che strumenti ad alto rischio vengano eseguiti automaticamente, e le azioni sensibili restano dietro approvazione umana.

Supporto HTTP server

Codex supporta due tipi di MCP server:

• STDIO server: comunicazione con processo locale, adatta a strumenti che richiedono accesso al sistema locale, come Playwright MCP
• HTTP server: supporta bearer token e autenticazione OAuth

Playwright MCP usa STDIO, quindi per il setup standard non serve configurare HTTP.

---

Configurare Playwright MCP in Cursor

Cursor configura MCP tramite Settings UI, a differenza dei percorsi da riga di comando di Claude Code e Codex.

Passaggi nell’interfaccia

Secondo la documentazione ufficiale Playwright, la configurazione Cursor è:

1. Apri Cursor Settings (Cmd+, oppure dal menu Settings)
2. Vai alla pagina MCP (Settings -> MCP)
3. Fai clic su “Add new MCP Server”
4. Compila la configurazione:
   • Server name: playwright
   • Command type: npx
   • Command: @playwright/mcp@latest

Configurazione dei parametri standard

La configurazione MCP server di Cursor supporta i parametri standard di Playwright MCP:

• --headless: modalità senza finestra browser; in sviluppo headed è più facile da osservare
• --browser: scelta del browser (chrome/firefox/webkit/msedge)
• --output-dir: percorso della directory di output
• --storage-state: percorso del file con stato di login

La lista completa dei parametri è nella tabella seguente.

Riferimenti di configurazione

La documentazione MCP di Cursor è disponibile nella documentazione ufficiale di Cursor. Per i dettagli di Playwright MCP, usa come riferimento la documentazione ufficiale Playwright e il README Microsoft, e assicurati di usare il pacchetto ufficiale @playwright/mcp@latest.

---

Tabella dei parametri di configurazione standard

Playwright MCP offre diversi parametri per controllare comportamento del browser, confini di sicurezza e gestione dell’output.

Parametro	Funzione	Valore predefinito	Nota di sicurezza
--headless	Modalità senza mostrare la finestra del browser	false (headed)	In sviluppo usa headed per osservare le azioni del browser
--browser	Scegliere il tipo di browser	chrome	Opzioni: chrome, firefox, webkit, msedge
--allowed-origins	Elenco di origin consentite	Nessun limite	Non è un confine di sicurezza; non influisce sui redirects e non protegge da solo siti sensibili
--blocked-origins	Elenco di origin bloccate	Nessuno	Non è un confine di sicurezza, stessa avvertenza
--isolated	Modalità isolata, ogni sessione usa un profile separato	false	Consigliato per client concorrenti o più progetti
--storage-state	Percorso del file di stato di login	Nessuno	Salva cookies e localStorage; attenzione con account reali
--output-dir	Directory di output per screenshot, log e simili	Nessuno	Imposta un percorso per trovare facilmente i risultati
--save-session	Salvare lo stato della sessione	false	Da usare con persistent profile
--snapshot-mode	Modalità dell’accessibility snapshot	default	Controlla il livello di dettaglio dello snapshot
--allow-unrestricted-file-access	Consentire accesso illimitato ai file	false	Alto rischio, abilitalo con cautela
--secrets	Configurazione dei secrets tramite variabili d’ambiente o file	Nessuno	Serve a gestire informazioni sensibili

Promemoria importante: la documentazione ufficiale dice chiaramente che --allowed-origins e --blocked-origins non sono confini di sicurezza e non influiscono sui redirects. Se devi limitare i siti che l’IA può visitare, non basarti solo su questi parametri.

---

Confronto tra tre modalità di profile

Playwright MCP supporta tre modalità di profile, che influenzano salvataggio dello stato di login, concorrenza e confini di sicurezza.

Modalità	Salvataggio dello stato di login	Percorso profile	Concorrenza	Quando usarla	Consiglio di sicurezza
persistent	Salva cookies, localStorage e altro	macOS: ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}	Un profile può essere usato da una sola browser instance alla volta	Task lunghi in cui l’IA deve ricordare il login	Evita account reali, parti da un account di test
isolated	Non salva, ogni sessione è indipendente	Directory temporanea, pulita a ogni sessione	Supporta client concorrenti o più progetti	Test, esplorazione, task senza login	Scelta consigliata in produzione
browser extension	Salva in base al browser	Directory dell’estensione browser	Dipende dal browser	Connessione a una sessione browser esistente	Uso avanzato, richiede di capire il modello di sicurezza delle estensioni

Limite del persistent profile

Un persistent profile può essere usato da una sola browser instance alla volta. Se devi usare più client o più progetti in parallelo con Playwright MCP, serve:

• usare la modalità --isolated
• oppure configurare un --user-data-dir diverso per ogni client

Esempio di percorso persistent profile su macOS:

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

La parte {workspace-hash} viene generata automaticamente in base al progetto, quindi progetti diversi usano profile diversi.

Stato di login e confini di sicurezza

Un persistent profile salva cookies, localStorage e sessionStorage. L’IA può accedere allo stato di login salvato nel browser. Se usi un account reale, può potenzialmente accedere a dati personali, informazioni di pagamento e impostazioni dell’account.

Pratiche consigliate:

• In produzione usa --isolated, così lo stato di login non viene salvato
• Se l’IA deve operare con uno stato di login, usa un account di test, non un account reale
• Non lasciare che l’IA faccia login automatico nel tuo account reale o visiti pagine di pagamento

La gestione dello stato di login verrà approfondita in un articolo successivo sui login state dei browser IA. Qui fissiamo solo il confine.

---

Avviso di sicurezza su browser_run_code_unsafe

Avviso di sicurezza: browser_run_code_unsafe consente di eseguire script Playwright arbitrari. La documentazione ufficiale lo marca come RCE-equivalent. Abilitalo solo per MCP clients completamente affidabili. In produzione, disattivalo o richiedi approvazione umana tramite approval_mode: prompt in Codex.

Playwright MCP include uno strumento ad alto rischio chiamato browser_run_code_unsafe. Può eseguire qualunque script Playwright nel contesto del browser. Il pericolo è diretto:

• Se l’MCP client viene compromesso o il comportamento dell’IA non è controllabile, un attaccante può usare questo strumento per eseguire codice arbitrario
• L’IA può leggere tutti i dati del browser, inclusi cookies, localStorage, sessionStorage e dati personali degli account loggati
• Se il browser sta visitando una pagina di pagamento o impostazioni account, l’IA può leggere ed esfiltrare dati sensibili

Raccomandazioni di configurazione sicura

Ambiente di produzione:

1. Disattiva browser_run_code_unsafe:

   Aggiungi questo in ~/.codex/config.toml di Codex:

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

2. Oppure imposta la modalità di approvazione:

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

   Così Codex mostrerà una conferma prima di ogni chiamata a browser_run_code_unsafe, e dovrai approvarla manualmente.

Ambiente di sviluppo:

Se devi davvero usare browser_run_code_unsafe:

• Abilitalo solo nello sviluppo locale, non in produzione o con account reali
• Assicurati di capire completamente lo script che verrà eseguito
• Non lasciare che l’IA generi ed esegua script automaticamente; scrivi tu lo script e fai eseguire all’IA quello script noto

Non consigliato ai principianti

Se stai iniziando con Playwright MCP, non partire da browser_run_code_unsafe. Usa prima strumenti Playwright MCP più sicuri, come browser_click, browser_navigate e browser_screenshot. Hanno confini più chiari e non eseguono codice arbitrario.

---

Checklist di sicurezza per MCP Tools

MCP permette all’IA di chiamare strumenti esterni, ma “collegare MCP” non significa “lasciare che l’IA faccia qualunque cosa in automatico”. Devi controllare i confini di sicurezza sia lato client sia lato server.

Raccomandazioni di sicurezza lato client

1. Chiedi conferma per le azioni sensibili: prima di chiamare browser_run_code_unsafe, visitare pagine di pagamento, modificare impostazioni account o cancellare dati, chiedi conferma all’utente. Non lasciare che l’IA esegua automaticamente queste operazioni ad alto rischio.

2. Mostra i tool inputs prima dell’esecuzione: l’utente deve vedere i parametri concreti che l’IA sta per usare. Per esempio, se l’IA vuole cliccare un pulsante, mostra selector o coordinate e conferma che siano corretti.

3. Previeni fughe di dati malevole: controlla l’output degli strumenti per evitare che informazioni sensibili, come password, token o dati personali, vengano lette dall’IA e mandate altrove. Se uno strumento restituisce dati sensibili, non lasciare che l’IA li scriva nei log o li invii a server esterni.

4. Imposta un timeout: le operazioni browser possono bloccarsi, consumare risorse o fermare altri task. Imposta un timeout ragionevole per ogni chiamata, per esempio 30 secondi, e annulla automaticamente al superamento.

5. Registra il tool usage: conserva log operativi per audit e diagnosi. Il log dovrebbe includere nome dello strumento, ora della chiamata, parametri di input, risultato e record di approvazione dell’utente.

6. Verifica i tool results: controlla che screenshot, console log e richieste di rete corrispondano al risultato atteso. Se l’IA dice “clic riuscito” ma lo screenshot non mostra cambiamenti, serve indagare.

Raccomandazioni di sicurezza lato server

Se sviluppi un MCP server personalizzato (Playwright MCP è già il server ufficiale, quindi non serve farlo), segui queste raccomandazioni:

1. Valida gli input: valida URL, selector e contenuti di input per prevenire injection. Non lasciare che l’IA passi URL malevoli o XSS payload senza controllo.

2. Controlla l’accesso: limita domini, percorsi file e capacità browser raggiungibili. Per esempio, blocca IP interni o percorsi sensibili.

3. Applica rate limiting: impedisci che l’IA chiami strumenti così spesso da esaurire risorse o farsi bloccare dal sito target. Imposta un limite ragionevole, come massimo 10 chiamate al minuto.

4. Pulisci l’output: rimuovi informazioni sensibili prima di restituire dati all’IA. Per esempio, non restituire stringhe cookie complete se basta una parte derivata.

---

Prima attività di verifica e checklist di accettazione

Dopo la configurazione, usa un task semplice per verificare che Playwright MCP sia collegato correttamente.

Esempio di task

Chiedi all’IA di aprire la preview locale http://localhost:4321, cliccare il menu di navigazione, fare uno screenshot e riportare console errors.

Passo dopo passo:

1. Assicurati che Playwright MCP sia stato aggiunto al tuo client, Claude Code, Codex o Cursor

2. Avvia il server di sviluppo locale, per esempio Astro o Next.js, e verifica che http://localhost:4321 sia raggiungibile

3. Inserisci questo prompt in Claude Code/Codex/Cursor:

   Apri http://localhost:4321, clicca "Articoli" nel menu di navigazione, fai uno screenshot e segnala se la pagina ha console errors.

4. Osserva se l’IA chiama gli strumenti browser, se il browser parte e se la pagina si apre

Checklist di accettazione

Controllo	Risultato atteso	Come verificarlo
Il browser si avvia	In headed mode si apre una finestra; in headless parte il processo	Osserva UI o process manager
MCP server connesso	I log del client mostrano “Connected to MCP server”	Controlla i log del client
accessibility snapshot restituito	L’IA trova il menu di navigazione e clicca	L’output dell’IA include la descrizione dell’azione di clic
La chiamata allo strumento richiede approvazione	Dipende dalla configurazione; Codex può mostrare una finestra di approvazione	Osserva se il client chiede conferma
Output e log sono tracciabili	Screenshot, console log e altri output compaiono in --output-dir	Controlla la directory configurata

Diagnosi degli errori

L’IA non chiama gli strumenti browser:

• Controlla nei log del client che l’MCP server sia stato aggiunto correttamente
• Verifica che il client supporti MCP Tool Search; Claude Code lo abilita di default
• Controlla che Node.js sia alla versione 18 o superiore

Il browser si apre ma non trova il pulsante:

• Playwright MCP lavora sull’accessibility tree, non sugli screenshot. Se la pagina non ha label semantiche o attributi ARIA, l’IA potrebbe non riconoscerla
• Controlla la struttura HTML della pagina e verifica che il pulsante abbia un label accessibile o un role
• Oppure usa il parametro --snapshot-mode per regolare il dettaglio dello snapshot

Il browser parte ma si chiude subito:

• Potrebbe essere headless mode o lo script potrebbe essere terminato
• Controlla i log del client e verifica se il browser è partito e si è chiuso normalmente
• Se usi headed mode, la finestra del browser dovrebbe restare aperta finché l’IA non segnala il completamento

---

Quando scegliere Playwright MCP rispetto a CLI/SKILLS

Il README ufficiale Microsoft osserva che, per coding agents in workflow di codice ad alto throughput, CLI + SKILLS può essere più adatto, perché MCP porta tool schema e accessibility tree nel contesto e consuma token. MCP è più indicato quando servono stato persistente, introspection ricca e contesto browser continuo per automazione esplorativa, test auto-riparanti o task lunghi.

Tabella di confronto per scenario

Scenario	Playwright MCP consigliato	Playwright CLI + SKILLS consigliato
Automazione esplorativa, test auto-riparanti	Sì, adatto	No, non adatto
Task lunghi con contesto browser persistente	Sì, adatto	No, non adatto
Workflow di codice ad alto throughput	No, consuma più contesto	Sì, adatto
Necessità di consumo minimo del contesto	No, non adatto	Sì, adatto
Usi già un MCP client come Claude Code/Codex/Cursor	Sì, adatto	No, non adatto

Questo articolo non entra nei dettagli dell’uso di SKILLS. Un articolo successivo parlerà della verifica browser con Codex nella pratica.

---

Riepilogo e prossimi passi

Questa guida ha coperto la configurazione di Playwright MCP per Claude Code, Codex e Cursor, la checklist di prima verifica e i confini di sicurezza: rischio RCE di browser_run_code_unsafe, persistenza dello stato di login nelle modalità di profile e il fatto che --allowed-origins non sia un confine di sicurezza.

Riepilogo delle differenze di configurazione

• Claude Code: usa claude mcp add o .mcp.json a livello di progetto; Tool Search è abilitato di default
• Codex: usa codex mcp add o config.toml; approval_mode controlla gli strumenti ad alto rischio
• Cursor: configura da Settings UI, con un percorso diverso dagli altri due

Prossimi passi consigliati

• Ti serve un confronto tra strumenti: leggi Browser Use vs Stagehand vs Playwright MCP, guida 2026 alla scelta degli strumenti browser IA
• Ti serve gestire lo stato di login: leggi Gestione dello stato di login nei browser IA
• Ti servono test frontend: leggi Test e verifica frontend con Playwright
• Ti serve la verifica browser con Codex: leggi Verifica browser con Codex nella pratica
• Ti serve infrastruttura gestita: leggi Infrastruttura browser gestita
• Ti serve progettare sicurezza e approvazioni: leggi Sicurezza dei browser IA e design delle approvazioni

Se hai appena configurato Playwright MCP, esegui prima il task di verifica su localhost:4321. Conferma che il browser parta, che l’IA chiami gli strumenti e che gli screenshot vengano scritti nella directory configurata. Se qualcosa fallisce, segui la FAQ e controlla versione di Node.js, log del client e stato di connessione dell’MCP server.