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.

Related MCP server: Claude Code Connector MCP

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):

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

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.)

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.