# vscode-terminal-mcp [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/sirlordt/vscode-terminal-mcp  
**GitHub Stars:** 2  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/vscode-terminal-mcp

## Description
Execute commands in visible VSCode terminal tabs with output capture and session reuse.

## Tools
Capabilities this server exposes over MCP:

- **run** — Create (or reuse) a terminal and execute a command in one step. Returns clean output with exit code.
- **create** — Create a new visible terminal session. Returns a `sessionId`.
- **exec** — Execute a command in an existing session and capture output.
- **read** — Read output from a session with pagination. Supports incremental reads and tail mode (`offset: -N`).
- **input** — Send text to an interactive terminal (prompts, REPLs, confirmations).
- **list** — List active sessions. Optionally filter by `agentId`.
- **close** — Close a terminal session and its VSCode tab.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What vscode-terminal-mcp does

The vscode-terminal-mcp MCP server exposes VS Code terminal tabs as MCP tools for command execution and session management. Commands run in terminals that remain visible in the editor, so users can watch output, scroll through logs, and interact with processes directly rather than receiving output only inside an agent conversation.

The `run` tool combines session creation or reuse with command execution and returns captured output plus an exit code. For more control, an agent can create a session, execute multiple commands in it, read buffered output, send input, list sessions, and close a session and its tab.

## How it works

A VS Code extension activates an IPC server on a Unix socket. The MCP entry point communicates with that extension, which creates and manages the visible terminal sessions. The setup therefore requires VS Code to be available for the extension and Node.js to launch the MCP entry point.

Sessions preserve terminal state between commands. The `run` operation can reuse an idle session instead of opening a new tab. Long-running commands can be started without waiting for completion, then checked with `read`. Incremental reads support offsets, including negative offsets for retrieving the most recent lines. Interactive workflows use `read` to inspect a prompt and `input` to provide a response.

Sessions may be tagged with an `agentId`. The `list` tool can filter by that identifier, which helps keep output from parallel agent workloads separated.

## Setup and configuration

The vscode-terminal-mcp MCP server requires VS Code 1.93 or newer for the Shell Integration API and Node.js 20 or newer. It can be launched with `npx vscode-terminal-mcp@latest`.

For Claude Code, add it with `claude mcp add BashTerm -- npx vscode-terminal-mcp@latest`. VS Code and Copilot use a `.vscode/mcp.json` entry with a stdio server whose command is `npx` and whose argument is `vscode-terminal-mcp@latest`. Cursor and Claude Desktop use their respective MCP configuration files with `npx -y vscode-terminal-mcp@latest`.

VS Code settings under `terminalMcp.*` control behavior:

- `terminalMcp.maxSessions` limits concurrent sessions and defaults to 10.
- `terminalMcp.commandTimeout` sets the default timeout in milliseconds and defaults to 30,000.
- `terminalMcp.maxOutputLines` limits buffered lines per session and defaults to 5,000.
- `terminalMcp.idleTimeout` closes idle sessions after the configured duration; its default is 1,800,000 ms, and `0` disables it.
- `terminalMcp.blockedCommands` defines rejected commands and defaults to `rm -rf /`.

## Tools and capabilities

- `run`: Create or reuse a terminal, execute a command, and return output with an exit code.
- `create`: Open a visible terminal session and return its `sessionId`.
- `exec`: Run a command in an existing session and capture its output.
- `read`: Retrieve session output with pagination, incremental reads, or tail-style offsets.
- `input`: Send text to prompts, REPLs, and confirmation dialogs.
- `list`: Show active sessions, optionally filtered by `agentId`.
- `close`: End a session and close its VS Code terminal tab.

## Limitations and notes

Output-heavy commands can exceed an MCP client’s token limit. In that case, the complete response is saved to a temporary JSON file and the error reports its path. Reading a smaller tail, such as the last 10 or 20 lines, reduces the amount returned to the client.

The visible-terminal behavior depends on the VS Code extension being active. Session limits, command timeouts, output retention, idle cleanup, and blocked commands are controlled by the VS Code settings rather than MCP tool arguments alone.

_Full upstream README: https://allmcps.com/mcp/vscode-terminal-mcp/readme_