vscode-terminal-mcp

Servidor MCP que ejecuta comandos en pestañas de terminal visibles de VSCode con captura completa de la salida. A diferencia de la ejecución en línea, cada comando se ejecuta en un terminal real que puedes ver, desplazarte e interactuar con él.

Características principales

• Terminales visibles: Los comandos se ejecutan en pestañas de terminal reales de VSCode, no en procesos ocultos. Ves todo en tiempo real.

• Reutilización de sesiones: La herramienta run reutiliza automáticamente las sesiones inactivas, creando nuevos terminales solo cuando es necesario.

• Soporte para procesos de larga duración: Ejecución de tipo "dispara y olvida" con waitForCompletion: false, y luego consulta la salida de forma incremental con read.

• Aislamiento de subagentes: Etiqueta las sesiones con agentId para mantener separadas las cargas de trabajo de agentes paralelos.

Related MCP server: Terminal MCP

Requisitos

• VS Code 1.93+ (para la API de integración de shell)

• Node.js 20+

Primeros pasos

Claude Code

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

VS Code / Copilot

Añade a tu .vscode/mcp.json:

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

Añade a tu .cursor/mcp.json:

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

Añade a tu claude_desktop_config.json:

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

Tu primer prompt

Después de la instalación, prueba a preguntar:

Ejecuta ls -la en el terminal

Deberías ver una nueva pestaña de terminal abrirse en VSCode con la salida del comando.

Capturas de pantalla

Ejecutando un comando con run

Diálogo de permisos para exec

Resultado de exec con salida limpia

Herramientas

Ejecución rápida

Gestión de sesiones

Patrones de uso

Comando simple

La herramienta run se encarga de todo: crea un terminal si es necesario, ejecuta y devuelve una salida limpia:

> Run npm test

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

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

Proceso de larga duración

Para compilaciones, despliegues o cualquier comando que tarde un tiempo:

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

El agente hará lo siguiente:

1. Llamar a run con waitForCompletion: false — devuelve inmediatamente

2. Llamar a read con offset: -10 para comprobar las últimas 10 líneas

3. Repetir hasta que el proceso se complete

Comandos interactivos

Para comandos que necesitan entrada del usuario:

> Run npm init and answer the prompts

El agente hará lo siguiente:

1. Llamar a run con npm init

2. Llamar a read para ver el prompt

3. Llamar a input para enviar la respuesta

Agentes paralelos

Los subagentes pueden trabajar en terminales aislados usando agentId:

> Have one agent run tests while another runs the linter

Cada subagente tiene su propio terminal etiquetado con su agentId, evitando que las salidas se mezclen.

Configuración

La extensión lee la configuración de los ajustes de VSCode bajo terminalMcp.*:

Recomendado: Configurar como herramienta preferida

Los agentes LLM como Claude Code tienen una herramienta Bash integrada que ejecuta comandos en línea dentro del chat. La salida queda incrustada en la conversación y es difícil de leer, especialmente para comandos con salida verbosa. Recomendamos indicar al agente que prefiera este MCP sobre su herramienta Bash integrada.

Añade lo siguiente al archivo CLAUDE.md de tu proyecto (o al archivo de instrucciones equivalente):

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

Por qué es importante:

Desarrollo: Actualizar la extensión

VSCode almacena en caché las extensiones de forma agresiva en memoria. Cuando desarrollas localmente, code --install-extension e incluso "Developer: Reload Window" pueden no recargar tus cambios. Usa este flujo de trabajo:

Actualización rápida (sin necesidad de reiniciar)

Después de modificar los archivos fuente, compila y copia directamente al directorio de la extensión instalada:

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

Luego ejecuta "Developer: Reload Window" (Ctrl+Shift+P).

Reinstalación completa (cuando la actualización rápida no funciona)

Si VSCode sigue usando código antiguo:

# 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

Verifica que se ha cargado la versión correcta

# 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

Manejo de salidas grandes

Cuando read devuelve una salida que supera el límite de tokens del cliente MCP, el sistema guarda automáticamente la salida completa en un archivo JSON temporal y devuelve la ruta del archivo en el mensaje de error.

Para extraer el contenido relevante:

# 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:])"

El formato del archivo es JSON: [{"type": "text", "text": "..."}]

Esto ocurre comúnmente con comandos que producen salida TUI pesada (barras de progreso, códigos de escape ANSI). Usa valores de offset más pequeños (por ejemplo, offset: -20 en lugar de offset: -100) para reducir el tamaño de la salida capturada.

Cómo funciona

1. La extensión de VSCode se activa e inicia un servidor IPC en un socket Unix

2. El punto de entrada MCP (mcp-entry.js) es lanzado por el cliente MCP y hace de puente entre JSON-RPC stdio y el socket IPC

3. Los comandos se ejecutan en terminales reales de VSCode usando la API de integración de shell para una captura fiable de la salida y detección del código de salida

4. La salida se almacena en buffers circulares con soporte de paginación para una lectura eficiente

Últimos cambios (0.1.6)

• Capturas de pantalla en el README para el marketplace

• Formato de salida limpio para todas las herramientas — sin JSON crudo

• Corregido waitForCompletion: false que no funcionaba

• Recolector de inactividad desactivado — el usuario cierra las sesiones manualmente

• Socket IPC único por espacio de trabajo (soporte multi-instancia)

• Nombres de pestañas de terminal personalizados con formato de fecha

• Documentación sobre manejo de salidas grandes

Consulta CHANGELOG.md para el historial completo.

Licencia

MIT