mcp-start-claude

Server MCP (trasporto SSE) che espone un tool per avviare Claude Code in una cartella di progetto specifica, aprendo una sessione interattiva in un nuovo terminale.

Pensato principalmente per Linux: rileva automaticamente l'emulatore di terminale disponibile, in ordine di preferenza:

gnome-terminal, ptyxis, konsole, xfce4-terminal, tilix, terminator, alacritty, kitty, wezterm, foot, x-terminal-emulator (fallback Debian), xterm.

Su WSL, se non è installato alcun terminale Linux, ricade su Windows Terminal (wt.exe) entrando nel distro WSL.

Requisiti

• Node.js ≥ 18
• claude (Claude Code CLI) nel PATH dell'utente che avvia il server
• Un emulatore di terminale tra quelli sopra e una sessione grafica (DISPLAY o WAYLAND_DISPLAY). In ambiente headless il tool restituisce un errore esplicito anziché fingere un avvio riuscito.

Installazione

npm install
npm run build

Avvio

La radice di accesso è obbligatoria: si passa come argomento (o via BASE_DIR). Il tool potrà aprire solo cartelle al suo interno; senza una radice valida il server non parte.

Il modo più comodo è creare un file .env (copiando .env.example): all'avvio viene caricato in automatico, così basta npm start senza argomenti.

cp .env.example .env   # poi modifica BASE_DIR ecc.
npm start              # http://127.0.0.1:3939/sse — legge .env

# In alternativa, passando i parametri a mano (hanno la PRECEDENZA sul .env):
npm start -- /home/ubuntu/projects
BASE_DIR=/home/ubuntu/projects npm start

Variabili d'ambiente (da .env, env reali o argomenti):

Variabile	Default	Descrizione
PORT	3939	Porta del server SSE
HOST	127.0.0.1	Host di bind
BASE_DIR	obbligatoria	Radice di accesso. Alternativa all'argomento CLI. Il tool apre solo cartelle al suo interno (con protezione anti-traversal e anti-symlink)
MCP_TERMINAL	autodetect	Forza il terminale per nome del binario (es. gnome-terminal, konsole, alacritty, kitty, wt.exe)
CLAUDE_REMOTE_CONTROL	attivo	Avvia con --remote-control. Imposta 0/false/off/no per disattivarlo

Endpoint

• GET /sse — stream SSE (handshake MCP, trasporto SSE)
• POST /messages?sessionId=... — messaggi del client (trasporto SSE)
• POST /mcp — trasporto Streamable HTTP stateless (standard MCP attuale)
• GET /health — stato e numero di sessioni attive

Il server espone entrambi i trasporti: SSE (come da requisito) e Streamable HTTP. Per i client moderni (es. mcp-remote, connettori nativi) usa /mcp, che è la prima scelta ed evita il client SSE di fallback.

Tool esposto

start_claude_code

Parametro	Tipo	Obbligatorio	Descrizione
projectPath	string	sì	Cartella in cui avviare Claude Code. Deve stare dentro la radice di accesso (relativa ad essa o assoluta al suo interno); fuori radice è rifiutata
prompt	string	no	Prompt iniziale della sessione

Apre un nuovo terminale, entra nella cartella e lancia claude --remote-control (Remote Control abilitato all'avvio; disattivabile con CLAUDE_REMOTE_CONTROL). L'eventuale prompt è passato come messaggio iniziale. Dopo l'uscita di Claude Code resta una shell interattiva (lo script si autoelimina).

Registrazione in Claude Code

Con il server in esecuzione:

claude mcp add --transport sse start-claude http://127.0.0.1:3939/sse

Poi, da Claude Code, basta chiedere di avviare Claude Code in una cartella e verrà invocato il tool start_claude_code.

Uso con Claude Desktop (da WSL)

Claude Desktop gira su Windows, il server in WSL. Si usa il bridge mcp-remote dentro WSL (così parla col server su 127.0.0.1, senza forwarding Windows↔WSL). Entry in claude_desktop_config.json:

{
  "mcpServers": {
    "start-claude": {
      "command": "wsl.exe",
      "args": [
        "bash",
        "-lc",
        "export NVM_DIR=/home/ubuntu/.nvm; . /home/ubuntu/.nvm/nvm.sh; exec npx -y mcp-remote http://127.0.0.1:3939/mcp --allow-http"
      ]
    }
  }
}

⚠️ Due trappole, entrambe già gestite nel comando sopra:

1. La login shell avviata da wsl.exe non carica nvm e cadrebbe sul Node di sistema (es. v18), troppo vecchio per mcp-remote (ReferenceError: File is not defined). Per questo si fa il source esplicito di nvm.sh.
2. Le virgolette doppie dentro il comando vengono mangiate passando per wsl.exe (es. "$HOME/.nvm" → variabile vuota). Usare quindi un path assoluto senza virgolette (/home/<utente>/.nvm).

Procedura:

1. In WSL, dal tuo terminale interattivo aperto sul desktop, avvia il server indicando la radice di accesso: npm start -- /home/ubuntu/projects (lasciarlo in esecuzione). Vedi sotto perché il terminale conta.
2. Riavviare completamente Claude Desktop (uscire dalla tray, non solo chiudere la finestra) così ricarica il config e avvia il bridge.
3. Il tool start_claude_code diventa disponibile in chat.

⚠️ Il server va avviato dalla tua sessione desktop interattiva. wt.exe viene lanciato tramite la WSL interop (WSL_INTEROP) del processo che lo esegue: se il server gira in un'altra sessione WSL (es. avviato da un agente, da un servizio o via SSH), wt.exe esegue ma la finestra compare in una sessione non visibile. Avviando npm start dal tuo terminale, le finestre si aprono sul tuo schermo. (Verifica veloce della sessione: lancia wt.exe dal terminale; se si apre una finestra, è quella giusta per npm start.)

Accesso da mobile: Cloudflare Tunnel + Access

I connettori di Claude (web e mobile) vengono raggiunti dal cloud di Anthropic, non dal tuo dispositivo: serve quindi un endpoint pubblico con certificato valido (una VPN privata non basta). Si ottiene con un Cloudflare Tunnel, e l'autenticazione la gestisce Cloudflare Access (nessun codice OAuth da scrivere lato server).

[Cloud Anthropic] → https://mcp.pawsolutions.it  (TLS valido, Cloudflare)
   → Cloudflare Access (gate OAuth: passa solo chi rispetta la policy)
   → Cloudflare Tunnel (cloudflared, connessione in uscita: nessuna porta aperta)
   → http://localhost:3939/mcp  (server MCP locale) → apre il terminale

Setup (una tantum, dashboard Cloudflare Zero Trust)

1. Networks → Tunnels → Create a tunnel (tipo Cloudflared). Copia il token e mettilo in .env come TUNNEL_TOKEN=....
2. Nel tunnel, Public Hostname: mcp.pawsolutions.it → Service http://localhost:3939. (Il record DNS viene creato da Cloudflare.)
3. Access → Applications → Add → Self-hosted, dominio mcp.pawsolutions.it. Aggiungi una policy che consenta solo la tua identità (es. Emails = la tua email; metodo di login Google/GitHub/OTP). Access gestirà l'intero flusso OAuth per il client MCP.

Avvio

npm start            # server MCP sull'host (HOST=0.0.0.0)
docker compose up -d # avvia il tunnel cloudflared

Aggiungere il connettore (Claude Desktop / mobile)

Connettori → "Aggiungi connettore personalizzato" → URL https://mcp.pawsolutions.it/mcp, campi OAuth vuoti. Claude aprirà un login Cloudflare nel browser: autenticati una volta → Access rilascia i token → solo la tua identità potrà usare il server.

⚠️ Sicurezza

• Il server MCP non ha autenticazione propria: l'autenticazione è demandata a Cloudflare Access. Senza una policy Access corretta, l'URL pubblico esporrebbe un launcher di terminali a chiunque — la policy è obbligatoria.
• Difesa in profondità (opzionale): il server può validare l'header Cf-Access-Jwt-Assertion iniettato da Access.
• HOST=0.0.0.0 espone la 3939 in chiaro sulla LAN (per il bridge Desktop e per cloudflared): se non ti serve l'accesso LAN, limitala con un firewall.

La vecchia variante con Caddy + certificato self-signed (Caddyfile, install_certificate.sh) non funziona con i connettori remoti (cert non pubblico) ed è superata da questo setup. I file restano nel repo solo come riferimento per un eventuale client che giri sullo stesso host.

Note tecniche

• Ogni connessione SSE crea un'istanza isolata del server MCP, indicizzata per sessionId.
• Il comando viene generato in uno script temporaneo per evitare problemi di escaping su più livelli (wt.exe → wsl.exe → bash); il prompt è quotato in POSIX.
• Il path assoluto di claude viene risolto lato server (ereditando nvm), così il terminale appena aperto non deve ricaricare l'ambiente.
• Gli errori di spawn sono gestiti per non far cadere il server.