Installare Playwright MCP richiede un comando per agente. Il motivo per cui esistono comunque le guide di setup: gli errori che le persone incontrano non sono errori di installazione, sono sorprese di ambito e di formulazione che costano un'ora ciascuna se nessuno te le segnala.
Questa guida ti dà il percorso da copiare e incollare per Claude Code, Cursor e Codex, le tre modalità di errore che vale la pena conoscere in anticipo e qualcosa che quasi tutti i post di setup saltano del tutto: le tre situazioni in cui installare Playwright MCP è la scelta sbagliata fin dall'inizio.
Prerequisiti, così nulla di ciò che segue ti coglie di sorpresa: Node.js 18 o superiore nel PATH, un agente dell'elenco qui sopra e circa cinque minuti. Il server stesso è di Microsoft, gratuito e open source con licenza Apache-2.0; qui non serve alcun account né chiave API.
Cinque minuti per installarlo. Un minuto per capire quando non farlo.
Come si confronta Playwright MCP con Chrome DevTools MCP ed ego (lite)?
Playwright MCP è la scelta migliore quando un agente ha bisogno di uno snapshot di accessibilità strutturato e di un browser ripetibile controllato da Playwright. Chrome DevTools MCP è la via di debug migliore quando devi collegarti alla finestra Chrome già aperta sullo schermo. ego (lite) è la via migliore per il lavoro quotidiano quando il requisito è riusare i tuoi login esistenti senza occupare la tua finestra. Sono superfici di controllo diverse, non versioni intercambiabili dello stesso strumento.
| Percorso | Stato del browser | Ideale per | Costo da valutare |
|---|---|---|---|
| Playwright MCP | Profilo persistente proprio per impostazione predefinita; è disponibile la modalità isolata | Esplorazione consapevole del DOM, snapshot e script cross-browser | Contesto degli snapshot e configurazione della sessione |
| Chrome DevTools MCP | Può collegarsi al profilo Chrome attivo con l'auto-connect | Trace di performance, diagnostica della console e debug della scheda corrente | Chrome 144+, debug remoto e una finestra condivisa |
| ego (lite) | Eredita i siti con accesso effettuato in Space isolati | Attività dell'agente in background, parallele e autenticate | Installazione locale; nessun setup MCP o di porta di debug |
La regola decisionale è semplice: scegli Playwright MCP per un contesto browser nuovo e ispezionabile; scegli Chrome DevTools MCP per lo stato della pagina e delle prestazioni che stai già esaminando; scegli ego (lite) quando lo stato di valore è il tuo login esistente e l'agente deve lavorare accanto a te. Se il volume di token è il collo di bottiglia, il confronto con la CLI linkato qui sotto è un punto di partenza migliore che aggiungere altri strumenti MCP.
Come si configura Playwright MCP in Claude Code?
Un comando nella directory del tuo progetto:
claude mcp add playwright npx '@playwright/mcp@latest'Verificalo: avvia Claude Code, esegui /mcp e seleziona playwright. Dovresti vedere l'elenco degli strumenti (più di due dozzine nella versione attuale: browser_navigate, browser_click, browser_snapshot, browser_take_screenshot e gli altri). Poi chiedi un'azione reale:
Use playwright mcp to open a browser to example.comDovrebbe aprirsi una finestra Chrome visibile. Nota la formulazione "use playwright mcp": alle prime esecuzioni Claude a volte ricorre a Bash e a Playwright grezzo invece che agli strumenti MCP, e nominare esplicitamente lo strumento lo indirizza correttamente. Simon Willison documenta sia questo sia il dettaglio di ambito qui sotto.
Se preferisci modificare la configurazione direttamente, la voce equivalente che Claude Code salva è questa (per progetto, dentro ~/.claude.json):
"mcpServers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
Come si configura Playwright MCP in Cursor?
Apri Cursor Settings, vai su MCP, clicca Add new MCP Server e usa il blocco di configurazione standard (lo stesso JSON funziona in VS Code, Windsurf e nella maggior parte dei client MCP):
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}Verificalo: il server dovrebbe mostrare uno stato verde nell'elenco delle impostazioni MCP con i suoi strumenti enumerati. Poi in una chat chiedi all'agente di aprire una pagina e fare uno snapshot; approva la chiamata allo strumento quando richiesto. Se il server mostra rosso, è quasi sempre Node: controlla che node --version sia 18+ nella shell che Cursor eredita.
Due dettagli di posizionamento risparmiano agli utenti Cursor un riavvio confuso: la configurazione può vivere per progetto (.cursor/mcp.json nella radice del repo) o globalmente (~/.cursor/mcp.json), e per quel workspace vince il file di progetto. La documentazione di Playwright fornisce anche un deeplink di installazione con un clic per Cursor se preferisci non toccare affatto il JSON.
Come si configura Playwright MCP in Codex?
Codex ha un comando add dedicato:
codex mcp add playwright npx "@playwright/mcp@latest"Questo scrive il server nella configurazione di Codex (~/.codex/config.toml). Verifica con codex mcp list, poi chiedi a Codex di navigare da qualche parte e leggere la pagina. Come con Claude Code, nomina lo strumento al primo uso così l'agente non improvvisa con comandi shell.
L'equivalente TOML, se gestisci il file a mano:
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]Tre flag utili da conoscere su ogni agente, da aggiungere all'array args: --headless per CI ed esecuzioni in background (headed è il default), --browser=firefox o webkit o msedge per il lavoro cross-browser e --isolated quando vuoi che ogni sessione parta da un profilo pulito invece che da quello persistente. Esiste anche una modalità server condiviso (npx @playwright/mcp@latest --port 8931) se più client devono guidare un solo browser via HTTP.
Quali sono i tre errori più comuni?
Tre errori coprono la maggior parte delle discussioni di setup su Reddit e GitHub. Ognuno ha una soluzione da trenta secondi.
| Sintomo | Causa | Soluzione |
|---|---|---|
| L'agente scrive uno script Playwright in Bash invece di usare l'MCP | Il modello ha scelto lo strumento che conosce meglio; non sa leggere le tue intenzioni | Di' esplicitamente "use playwright mcp" nel primo prompt di una sessione |
| Il server manca anche se l'hai installato | Ambito per directory: la configurazione vive nella cartella in cui hai eseguito il comando add | Riaggiungilo nel progetto corrente, oppure usa --scope user per un'installazione globale |
| La prima navigazione fallisce con un errore di avvio del browser | Nessun binario del browser per il runtime che npx ha scaricato | Chiedi all'agente di eseguire il suo strumento browser_install, oppure esegui tu npx playwright install chromium |
Se hai superato questi tre problemi e non funziona ancora, controlla Node (richiesto 18+) prima di ogni altra cosa; quasi ogni issue GitHub rimanente in questa categoria si risolve lì.
Una volta che è vivo, tre primi prompt che dimostrano il setup end to end, in ordine crescente di utilità: "use playwright mcp to open example.com and tell me the main heading" (navigazione e snapshot), "open our staging site, compila il modulo di iscrizione con un'email fittizia e riporta l'errore di validazione" (interazione con i form) e "open the pricing page, take a screenshot, and list every plan name you can see" (screenshot più estrazione).
Se passano tutti e tre, il resto è questione di prompt, e la domanda che rimane è se questo strumento si adatta al tuo carico di lavoro, ed è a questo che serve la sezione successiva.
Quando conviene saltare Playwright MCP?
Ora la parte che ti risparmia una reinstallazione il mese prossimo. Playwright MCP è il default giusto per brevi sessioni esplorative su pagine pubbliche. Tre situazioni rompono quel default, e ognuna punta a uno strumento di forma diversa:
| La tua situazione | Perché l'MCP è della forma sbagliata | Usa invece |
|---|---|---|
| Sensibile ai token: attività lunghe, budget stretti | Ogni azione restituisce uno snapshot della pagina; le esecuzioni misurate arrivano a 89K-114K token per test contro 24K-27K con una CLI | La Playwright CLI ufficiale, oppure ego (lite), un browser per agenti che restituisce snapshot semantici compatti con riferimenti stabili agli elementi e raggruppa più azioni in un'unica esecuzione JavaScript nella pagina per ridurre i passaggi |
| Attività dietro i login dei tuoi account | L'MCP avvia un profilo nuovo senza cookie; l'autenticazione è da script ogni volta | ego (lite): ogni sito in cui hai effettuato l'accesso resta connesso, e l'agente eredita quello stato |
| Più attività browser in parallelo | Una sola sessione browser sequenziale per impostazione predefinita; gli agenti in parallelo si pestano i piedi | Space di ego (lite): il tuo agente esegue oltre 100 attività browser contemporaneamente, ognuna nel proprio spazio di lavoro, così nulla entra in collisione con le schede che stai usando |
Sulle righe di ego (lite), la differenza di forma merita un'ultima frase: è un Chromium completo che usi anche per navigare, non un runtime solo per script.
Il suo setup rispecchia lo spirito copia-e-incolla di questa guida: un comando installa lo skill ego-browser, oppure un prompt affida tutto al tuo agente.
npx skills add citrolabs/ego-litePaste into your agent
Set up ego lite for me: https://github.com/citrolabs/ego-lite Read `skills/ego-browser/references/install.md` and follow the steps to install ego lite.
Nel nostro benchmark pubblicato quella combinazione completa le stesse attività con il 44% in meno di round di esecuzione, il 35.5% in meno di chiamate agli strumenti e il 21.6% di costi in meno rispetto all'esecuzione comando per comando. L'harness e i dati sono pubblici nel repository ego-browser-benchmark-framework. Se la tua settimana include attività quotidiane su siti con login, configuralo prima e tieni Playwright MCP per l'esplorazione di pagine pubbliche in cui è bravo.
Scarica ego (lite) per Mac oppure vedi come si confronta con Playwright MCP funzionalità per funzionalità.
Domande frequenti
Come aggiungo Playwright MCP a Claude Code?
Esegui claude mcp add playwright npx '@playwright/mcp@latest' nella directory del tuo progetto, poi verifica con /mcp dentro Claude Code. Aggiungi --scope user se lo vuoi disponibile in ogni progetto.
Playwright MCP è gratuito da installare e usare?
Sì: Apache-2.0, mantenuto da Microsoft, installato via npm. Il costo di esercizio è il consumo di token, che sulle attività lunghe è il motivo per cui esiste la sezione "quando saltarlo" qui sopra.
Playwright MCP funziona in modalità headed o headless?
Headed è il default, così puoi guardare il browser lavorare; aggiungi --headless agli args per CI o esecuzioni in background. I flag cross-browser (--browser=firefox, webkit, msedge) funzionano in entrambe le modalità.
Come aggiorno o rimuovo Playwright MCP?
Gli aggiornamenti sono automatici con il tag @latest: npx scarica la release più recente a ogni avvio del server. La rimozione rispecchia l'installazione: claude mcp remove playwright, codex mcp remove playwright, oppure elimina il blocco da mcp.json di Cursor. Una cautela sull'aggiornamento automatico: la issue #889 sul repository ufficiale documenta una versione minore che ha moltiplicato per 6 l'uso dei token, quindi se i costi saltano all'improvviso, fissa una versione negli args.
Playwright MCP può usare il mio profilo Chrome con login?
Non quello quotidiano. Usa per impostazione predefinita un proprio profilo persistente, e puntare gli strumenti al tuo profilo Chrome reale si scontra con blocchi del profilo e conflitti di sessione. Se il requisito è ereditare i tuoi login esistenti, ego (lite) è la via per farlo: importi una volta la tua configurazione Chrome, l'agente lavora da quello stato con accesso effettuato e decidi tu quanto condividerne.
