Chrome DevTools MCP su WSL2: Claude Code senza uscire da Linux

Sviluppare in WSL2 con Claude Code è una scelta sempre più diffusa fra chi vuole un ambiente Linux pur restando su Windows come sistema host. La configurazione predefinita di chrome-devtools-mcp si scontra però con una difficoltà strutturale: il binario di Chrome vive su Windows, mentre il server MCP gira lato WSL, e il confine fra i due ambienti rende il collegamento tutt'altro che immediato. Questo articolo presenta la configurazione che si è dimostrata più stabile nella pratica quotidiana, ossia lanciare il server MCP attraverso cmd.exe e riusare direttamente il Chrome già installato su Windows, senza duplicare l'installazione del browser dentro WSL e senza richiedere passaggi manuali a ogni sessione di lavoro.

Perché chrome-devtools-mcp di default non funziona in WSL2

Il plugin ufficiale chrome-devtools-mcp è progettato per essere eseguito tramite npx chrome-devtools-mcp@latest in un ambiente Linux nativo. In WSL2 questa assunzione si scontra con un dettaglio non trascurabile: Chrome non è installato all'interno dell'istanza Linux, ma vive su Windows in C:\Program Files\Google\Chrome\Application\chrome.exe. Il server MCP, lanciato da WSL, tenta di istanziare un binario che non trova, oppure si scontra con i limiti del networking quando si prova a parlare con il Chrome di Windows attraverso /mnt/c/ o localhost.

La issue è tracciata pubblicamente come ChromeDevTools/chrome-devtools-mcp#131 ed è stata chiusa come feature request, senza una soluzione integrata nel plugin. In assenza di un fix ufficiale, nei thread di Reddit e Hacker News sono emerse tre strategie di workaround, di qualità ed ergonomia molto diverse fra loro.

Le tre strategie possibili a confronto

Le strade percorribili per far funzionare chrome-devtools-mcp su WSL2 con Claude Code sono essenzialmente tre. La differenza non riguarda soltanto il fatto che funzionino, ma quanto inquinano il workflow quotidiano e quanta autonomia lasciano all'agente nella gestione del browser.

La strategia B è quella che offre il miglior compromesso fra ergonomia, autonomia dell'agente e leggerezza del setup, ed è quella documentata nel resto dell'articolo. La strategia C resta un'alternativa valida per chi preferisce un ambiente totalmente isolato dal lato Windows ed è descritta nel confronto generale fra Claude Code e Codex.

Prerequisito spesso trascurato: Node anche su Windows

Per far funzionare la strategia B, Node deve essere installato non solo dentro WSL ma anche su Windows. Il motivo è semplice: il comando cmd.exe /c npx cerca un eseguibile di Node lato Windows, ed è quello che effettivamente lancia il server MCP. Una verifica veloce dal terminale WSL conferma la presenza dei binari necessari.

1cmd.exe /c "where npx"
2cmd.exe /c "node --version"

Configurare il server MCP a livello utente

Claude Code consente di registrare un server MCP in tre scope diversi. La scelta non è banale, perché ognuno ha implicazioni dirette sulla durabilità e sulla portabilità della configurazione.

Backup preventivo del file di configurazione

Prima di modificare ~/.claude.json, è buona pratica creare una copia di sicurezza. Il file contiene impostazioni globali della CLI e una corruzione accidentale comprometterebbe l'avvio.

1cp ~/.claude.json ~/.claude.json.bak

Modifica chirurgica della configurazione

La modifica può essere eseguita manualmente con un editor di testo oppure tramite un breve script Python che aggiunge la voce chrome-devtools dentro mcpServers senza toccare il resto del file. La versione script ha il vantaggio di preservare l'indentazione e tutte le altre chiavi presenti.

1import json
2 
3path = '/home/<user>/.claude.json'
4 
5with open(path) as f:
6    d = json.load(f)
7 
8d.setdefault('mcpServers', {})['chrome-devtools'] = {
9    "type": "stdio",
10    "command": "cmd.exe",
11    "args": [
12        "/c", "npx", "-y", "chrome-devtools-mcp@latest",
13        "--executable-path=C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
14    ]
15}
16 
17with open(path, 'w') as f:
18    json.dump(d, f, indent=2)

Sostituire <user> con il nome utente WSL effettivo. Il blocco aggiunto registra il server chrome-devtools indicando cmd.exe come comando di avvio e passando, fra gli argomenti, il percorso del chrome.exe di Windows. Da questo momento Claude Code è in grado di richiamare il server senza alcuna intermediazione manuale.

Disabilitare il plugin ufficiale senza perdere le skill

Una volta che il server user-level è operativo, il plugin ufficiale chrome-devtools-mcp@claude-plugins-official diventa ridondante. Lasciandolo attivo, Claude Code lo carica all'avvio e tenta di lanciare un Chrome lato WSL che non esiste, fallendo in modo silenzioso ed esponendo strumenti MCP che puntano a un server non funzionante. La rimozione si effettua editando ~/.claude/settings.json e commentando la riga corrispondente.

1"enabledPlugins": {
2  // rimuovere o commentare questa riga:
3  // "chrome-devtools-mcp@claude-plugins-official": true
4}

La soluzione consiste nel copiare le skill in ~/.claude/skills/, la directory dove Claude Code cerca le skill di livello utente, rinominando troubleshooting per evitare collisioni con altre skill omonime che potrebbero esistere nello stesso namespace.

1SRC=~/.claude/plugins/marketplaces/chrome-devtools-plugins/skills
2DST=~/.claude/skills
3 
4for s in a11y-debugging chrome-devtools chrome-devtools-cli debug-optimize-lcp memory-leak-debugging; do
5  cp -r "$SRC/$s" "$DST/"
6done
7 
8# troubleshooting rinominata per evitare collisioni di nome
9cp -r "$SRC/troubleshooting" "$DST/chrome-devtools-troubleshooting"

Dopo la copia, il frontmatter della skill rinominata va aggiornato perché il campo name sia coerente con il nome della cartella. Senza questa modifica la skill resta caricabile ma il nome interno risulta dissociato dal percorso, con possibili ambiguità in fase di referenziazione.

1---
2name: chrome-devtools-troubleshooting
3description: Uses Chrome DevTools MCP and documentation to troubleshoot common issues with Claude Code
4---

Le skill a livello utente vengono caricate in hot reload, senza riavviare Claude Code. Per il server MCP, al contrario, il riavvio è necessario perché i server vengono inizializzati una volta sola all'apertura della sessione e le modifiche a ~/.claude.json non hanno effetto retroattivo sulle sessioni aperte.

Verifica funzionale tramite i log MCP

L'unico modo affidabile per sapere se chrome-devtools-mcp è realmente collegato è leggere i log che Claude Code genera per ogni server MCP. I file si trovano nella seguente directory:

1~/.cache/claude-cli-nodejs/<project-slug>/mcp-logs-chrome-devtools/

Nel file .jsonl più recente vanno cercati tre eventi distinti che, in sequenza, confermano una connessione corretta del server: l'inizio del tentativo di connessione, la conferma del trasporto stdio e la negoziazione delle capabilities.

1{"debug":"Starting connection with timeout of 30000ms", ...}
2{"debug":"Successfully connected (transport: stdio) in 1586ms", ...}
3{"debug":"Connection established with capabilities: {\"hasTools\":true,\"serverVersion\":{\"name\":\"chrome_devtools\",\"version\":\"1.0.1\"}}", ...}

Eventuali messaggi su stderr del tipo 'I percorsi UNC non sono supportati' sono rumore innocuo prodotto da cmd.exe quando viene invocato da una working directory che inizia con \\wsl.localhost. Non compromettono il funzionamento del server e possono essere ignorati.

Profilo Chrome reale: usare cookie e login esistenti

In alcune situazioni avere un Chrome che parte sempre da un profilo pulito è limitante. È il caso del testing di flussi che richiedono autenticazione, oppure dell'ispezione di pagine dietro sessioni già attive su servizi terzi. Per fare in modo che Chrome avvii con un profilo utente esistente, basta aggiungere il parametro --userDataDir agli argomenti del server MCP.

1"args": [
2  "/c", "npx", "-y", "chrome-devtools-mcp@latest",
3  "--executable-path=C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
4  "--userDataDir=C:\\Users\\<USERNAME>\\AppData\\Local\\Google\\Chrome\\User Data"
5]

Riepilogo operativo

• Verificare la presenza di Node e npx su Windows, non solo dentro WSL
• Eseguire il backup di ~/.claude.json prima di qualsiasi modifica
• Aggiungere il server chrome-devtools nel blocco mcpServers di livello utente
• Disabilitare il plugin chrome-devtools-mcp dal file ~/.claude/settings.json
• Copiare le sei skill del plugin in ~/.claude/skills, rinominando troubleshooting
• Aggiornare il frontmatter name della skill rinominata
• Riavviare Claude Code e verificare nei log MCP la stringa 'Successfully connected'

In conclusione

La strategia basata su cmd.exe risolve in modo pulito la frizione fra WSL2 e Chrome DevTools MCP, evitando sia il workaround manuale del remote debugging sia la duplicazione del browser dentro l'istanza Linux. La chiave concettuale è accettare che cmd.exe possa funzionare come ponte fra i due ambienti, riusando l'infrastruttura Windows esistente invece di replicarla. Con questa configurazione il workflow di Claude Code su WSL2 si avvicina a quello di un ambiente Linux nativo, mantenendo al contempo i vantaggi operativi di Windows come sistema host (Office, gestione dispositivi, software specifici).