note rapide

note.md

Docker MCP Toolkit da WSL2 con Claude Code CLI

Guida per usare il Docker MCP Toolkit da WSL2 con Claude Code CLI, su una macchina Windows con Docker Desktop.

Prerequisiti

• Windows con Docker Desktop installato e in esecuzione
• WSL2 attivo con integrazione Docker Desktop abilitata (Docker Desktop → Settings → Resources → WSL Integration)
• Claude Code CLI installato in WSL2
• Docker MCP Toolkit abilitato in Docker Desktop (Settings → Beta features → Enable Docker MCP Toolkit)

---

Il problema

Quando Docker Desktop è in esecuzione su Windows, configura automaticamente MCP_DOCKER nel Claude Code di Windows, ma non in quello di WSL2.

Se da WSL2 esegui claude mcp list, MCP_DOCKER non compare — oppure compare con stato ✗ Failed to connect, perché il binary bundled con Docker Desktop cerca un socket (/run/host-services/tools.sock) che non esiste nel filesystem Linux di WSL2.

---

Soluzione

1. Installa il binary standalone di docker-mcp

Il binary incluso in Docker Desktop controlla la presenza di Docker Desktop tramite socket locali che non sono disponibili in WSL2. Il binary standalone da GitHub risolve il problema con la variabile d'ambiente DOCKER_MCP_IN_CONTAINER.

# Scarica l'ultima release (verifica la versione su github.com/docker/mcp-gateway)
curl -Lo /tmp/docker-mcp.tar.gz \
  https://github.com/docker/mcp-gateway/releases/download/v0.40.2/docker-mcp-linux-amd64.tar.gz

tar -xzf /tmp/docker-mcp.tar.gz -C /tmp/

mkdir -p ~/.docker/cli-plugins
cp /tmp/docker-mcp ~/.docker/cli-plugins/docker-mcp
chmod +x ~/.docker/cli-plugins/docker-mcp

Verifica:

docker mcp version
# v0.40.2

2. Aggiungi MCP_DOCKER a Claude Code

claude mcp add MCP_DOCKER -s user -e DOCKER_MCP_IN_CONTAINER=1 -- docker mcp gateway run

La variabile DOCKER_MCP_IN_CONTAINER=1 dice al gateway di non cercare Docker Desktop tramite socket locali, bypassando il controllo che causava l'errore Docker Desktop is not running.

3. Verifica

claude mcp list
# ...
# MCP_DOCKER: docker mcp gateway run - ✓ Connected

---

Usare i server MCP dal catalog Docker

Il gateway parte senza server abilitati, ma espone strumenti interni per gestirli dinamicamente direttamente dalla chat:

Tool interno	Cosa fa
mcp-find	Cerca server nel catalog Docker
mcp-add	Aggiunge e attiva un server nella sessione
mcp-remove	Rimuove un server
mcp-config-set	Configura parametri di un server

Esempio: in una sessione Claude Code, puoi scrivere:

"Cerca nel catalog Docker un server per i transcript YouTube e abilitalo"

Claude userà mcp-find e mcp-add in autonomia.

---

Note

• I container Docker per i server MCP partono on-demand e si spengono subito dopo l'uso — non girano in background.
• I secrets (API key, token) si gestiscono con docker mcp secret set.
• Il profilo MCP configurato in Docker Desktop su Windows non viene condiviso automaticamente con WSL2: la configurazione WSL2 è indipendente.
• Il binary ~/.docker/cli-plugins/docker-mcp sovrascrive quello bundled con Docker Desktop. In caso di aggiornamento di Docker Desktop, potrebbe essere necessario aggiornare anche questo binary.