vscode-terminal-mcp

MCP-Server, der Befehle in sichtbaren VSCode-Terminal-Tabs mit vollständiger Ausgabeerfassung ausführt. Anders als bei der Inline-Ausführung läuft jeder Befehl in einem echten Terminal, das du sehen, scrollen und mit dem du interagieren kannst.

Hauptfunktionen

• Sichtbare Terminals: Befehle laufen in echten VSCode-Terminal-Tabs, nicht in versteckten Prozessen. Du siehst alles in Echtzeit.

• Sitzungswiederverwendung: Das run-Tool verwendet automatisch inaktive Sitzungen wieder und erstellt nur bei Bedarf neue Terminals.

• Unterstützung für langlaufende Prozesse: Fire-and-forget-Ausführung mit waitForCompletion: false, dann inkrementelles Abrufen der Ausgabe mit read.

• Subagent-Isolation: Sitzungen mit agentId markieren, um parallele Agenten-Workloads getrennt zu halten.

Related MCP server: Terminal MCP

Voraussetzungen

• VS Code 1.93+ (für Shell Integration API)

• Node.js 20+

Erste Schritte

Claude Code

claude mcp add BashTerm -- npx vscode-terminal-mcp@latest

VS Code / Copilot

Füge Folgendes zu deiner .vscode/mcp.json hinzu:

{
  "servers": {
    "BashTerm": {
      "type": "stdio",
      "command": "npx",
      "args": ["vscode-terminal-mcp@latest"]
    }
  }
}

Füge Folgendes zu deiner .cursor/mcp.json hinzu:

{
  "mcpServers": {
    "BashTerm": {
      "command": "npx",
      "args": ["-y", "vscode-terminal-mcp@latest"]
    }
  }
}

Füge Folgendes zu deiner claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "BashTerm": {
      "command": "npx",
      "args": ["-y", "vscode-terminal-mcp@latest"]
    }
  }
}

Dein erster Prompt

Nach der Installation kannst du zum Beispiel Folgendes versuchen:

Führe ls -la im Terminal aus

Du solltest sehen, wie sich ein neuer Terminal-Tab in VSCode öffnet, mit der Befehlsausgabe.

Screenshots

Ausführen eines Befehls mit run

Berechtigungsdialog für exec

Exec-Ergebnis mit sauberer Ausgabe

Tools

Schnelle Ausführung

Sitzungsverwaltung

Verwendungsmuster

Einfacher Befehl

Das run-Tool übernimmt alles – erstellt bei Bedarf ein Terminal, führt aus und gibt saubere Ausgabe zurück:

> Run npm test

$ npm test
PASS src/utils.test.ts (3 tests)
PASS src/index.test.ts (5 tests)

[exit: 0 | 1243ms | session-abc123]

Langlaufender Prozess

Für Builds, Bereitstellungen oder jeden Befehl, der eine Weile dauert:

> Start `npm run build` without waiting, then check progress

Der Agent wird:

1. run mit waitForCompletion: false aufrufen – gibt sofort zurück

2. read mit offset: -10 aufrufen, um die letzten 10 Zeilen zu prüfen

3. Wiederholen, bis der Prozess abgeschlossen ist

Interaktive Befehle

Für Befehle, die Benutzereingaben benötigen:

> Run npm init and answer the prompts

Der Agent wird:

1. run mit npm init aufrufen

2. read aufrufen, um den Prompt zu sehen

3. input aufrufen, um die Antwort zu senden

Parallele Agenten

Subagenten können in isolierten Terminals mit agentId arbeiten:

> Have one agent run tests while another runs the linter

Jeder Subagent erhält sein eigenes Terminal, das mit seiner agentId markiert ist, sodass sich Ausgaben nicht vermischen.

Konfiguration

Die Erweiterung liest die Konfiguration aus den VSCode-Einstellungen unter terminalMcp.*:

Empfohlen: Als bevorzugtes Tool festlegen

LLM-Agenten wie Claude Code haben ein integriertes Bash-Tool, das Befehle inline im Chat ausführt. Die Ausgabe ist in die Konversation eingebettet und schwer zu lesen, insbesondere bei Befehlen mit umfangreicher Ausgabe. Wir empfehlen, dem Agenten zu sagen, dass er dieses MCP seinem integrierten Bash-Tool vorziehen soll.

Füge Folgendes zu deiner CLAUDE.md (oder einer entsprechenden Anweisungsdatei) hinzu:

## Terminal Execution

Prefer the BashTerm MCP tools (`run`, `exec`, `read`, etc.) over the built-in Bash tool for executing commands.
BashTerm runs commands in visible VSCode terminal tabs where the user can see output in real time.
Only fall back to the built-in Bash tool for simple, non-interactive operations like reading environment variables.

For commands that may take longer than 30 seconds or produce large amounts of output (builds, test suites,
deployments, installs), use the pull mode pattern:
1. Call `run` with `waitForCompletion: false` to launch the command without blocking.
2. Call `read` with `offset: -10` to check the last 10 lines of output.
3. Repeat step 2 until you see the command has finished (look for exit messages, prompts, or "Done").
4. Report the final result to the user.

This prevents conversation timeouts and lets the user watch progress in the terminal in real time.

Warum das wichtig ist:

Entwicklung: Aktualisieren der Erweiterung

VSCode cached Erweiterungen aggressiv im Speicher. Bei lokaler Entwicklung kann code --install-extension und sogar „Developer: Reload Window“ deine Änderungen möglicherweise nicht neu laden. Verwende diesen Workflow:

Schnelles Update (kein Neustart nötig)

Nach dem Ändern von Quelldateien erstelle und kopiere direkt in das installierte Erweiterungsverzeichnis:

cd /path/to/vscode-terminal-mcp
npm run build
cp dist/extension.js ~/.vscode/extensions/sirlordt.vscode-terminal-mcp-<version>/dist/extension.js

Führe dann „Developer: Reload Window“ (Ctrl+Shift+P) aus.

Vollständige Neuinstallation (wenn das schnelle Update nicht funktioniert)

Wenn VSCode immer noch alten Code verwendet:

# 1. Uninstall and remove all copies
code --uninstall-extension sirlordt.vscode-terminal-mcp
rm -rf ~/.vscode/extensions/sirlordt.vscode-terminal-mcp-*

# 2. Check for ghost entries with old publisher names
# Look in ~/.vscode/extensions/extensions.json for stale entries
# Remove any entries with old publisher IDs (e.g., "terminal-mcp.vscode-terminal-mcp")

# 3. Close VSCode completely (not just reload)

# 4. Rebuild and install
npm run build
npx vsce package --allow-missing-repository
code --install-extension vscode-terminal-mcp-<version>.vsix --force

# 5. Open VSCode

Überprüfen, ob die richtige Version geladen ist

# Check which extension directories exist
ls ~/.vscode/extensions/ | grep terminal

# Verify your changes are in the installed extension
grep "YOUR_UNIQUE_STRING" ~/.vscode/extensions/sirlordt.vscode-terminal-mcp-*/dist/extension.js

# Compare checksums
md5sum dist/extension.js ~/.vscode/extensions/sirlordt.vscode-terminal-mcp-*/dist/extension.js

Umgang mit großen Ausgaben

Wenn read eine Ausgabe zurückgibt, die das Token-Limit des MCP-Clients überschreitet, speichert das System die vollständige Ausgabe automatisch in einer temporären JSON-Datei und gibt den Dateipfad in der Fehlermeldung zurück.

Um den relevanten Inhalt zu extrahieren:

# Get the last 50 lines (most relevant for status)
tail -50 /path/to/saved/file.txt

# Or parse the JSON to extract the text content
python3 -c "import json; data=json.load(open('/path/to/file.txt')); print(data[0]['text'][-2000:])"

Das Dateiformat ist JSON: [{"type": "text", "text": "..."}]

Dies passiert häufig bei Befehlen mit umfangreicher TUI-Ausgabe (Fortschrittsbalken, ANSI-Escape-Codes). Verwende kleinere offset-Werte (z. B. offset: -20 statt offset: -100), um die erfasste Ausgabegröße zu reduzieren.

So funktioniert es

1. Die VSCode-Erweiterung wird aktiviert und startet einen IPC-Server auf einem Unix-Socket

2. Der MCP-Einstiegspunkt (mcp-entry.js) wird vom MCP-Client gestartet und überbrückt JSON-RPC-stdio mit dem IPC-Socket

3. Befehle werden in echten VSCode-Terminals über die Shell Integration API ausgeführt, für zuverlässige Ausgabeerfassung und Exit-Code-Erkennung

4. Die Ausgabe wird in zirkulären Puffern mit Paginierungsunterstützung für effizientes Lesen gespeichert

Neueste Änderungen (0.1.6)

• Screenshots in README für den Marketplace

• Sauberes Ausgabeformat für alle Tools – kein rohes JSON mehr

• Fehler behoben: waitForCompletion: false funktionierte nicht

• Inaktiven Reaper deaktiviert – Benutzer schließt Sitzungen manuell

• Eindeutiger IPC-Socket pro Workspace (Multi-Instanz-Unterstützung)

• Benutzerdefinierte Terminal-Tab-Namen mit Datumsformat

• Dokumentation zur Handhabung großer Ausgaben

Vollständige Historie in CHANGELOG.md.

Lizenz

MIT