# smart-terminal [Health: Active]

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

## Description
MCP PTY server providing AI agents with real interactive terminal access

## Tools
Capabilities this server exposes over MCP:

- **terminal_start** — Start a new interactive terminal session.
- **terminal_exec** — Execute a command with deterministic completion detection. Large outputs are truncated to head + tail based on `maxLines`. If the MCP client sends a `progressToken`, long-running calls may also emit best-effort `notifications/progress` updates.
- **terminal_run** — Run a one-shot non-interactive command using `cmd + args` with `shell=false`. Safer than `terminal_exec` for predictable automation. Output is capped by `maxOutputBytes` rather than head + tail truncation. Shell built-ins such as `dir` or `cd` are not supported. On Windows, `terminal_run` resolves…
- **terminal_write** — Write raw data to a terminal (for interactive programs). Follow with `terminal_read`.
- **terminal_read** — Read buffered output with idle detection. Large outputs are truncated to head + tail based on `maxLines`. Pass `since` to read incrementally — returns only output emitted after the given byte position.
- **terminal_wait** — Wait for a specific pattern in the output stream. Only output produced **after the call** is matched by default — the echoed command line (which contains any pattern you typed, completion markers included) never triggers a match, including an echo that is still streaming in when the wait starts (wr…
- **terminal_stop** — Stop and clean up a terminal session. Optionally capture a snapshot of recent output or write the full transcript to disk before stopping. On Unix, kills the entire process group to prevent orphan child processes.
- **terminal_list** — List all active terminal sessions.
- **terminal_extra** — Meta-tool for discovering and calling extra tools.
- **terminal_send_key** — Send a named special key.
- **terminal_run_paged** — Run a read-only one-shot command using `cmd + args` with `shell=false` and return a single page of stdout lines from the captured output. This pages the returned result instead of using head + tail truncation. Paged mode does not parse partial output, but it can return a concise summary for support…
- **terminal_get_history** — Retrieve past terminal output without consuming it. Non-destructive — returns historical output from a rolling buffer (last ~10,000 lines). Useful for reviewing output that was already read or missed.
- **terminal_retry** — Retry a command in the same terminal session until it succeeds or retries are exhausted.
- **terminal_diff** — Run two commands in the same terminal session and return a bounded unified diff of their outputs.
- **terminal_resize** — Resize terminal dimensions.
- **terminal_write_file** — Write content directly to a file on disk. Resolves paths relative to the session's CWD. Safer and more robust than piping content through `echo` — handles special characters, newlines, and large files correctly.
- **terminal_watch** — Wait for one or more trigger patterns in session output. Returns on first match, quiet detection, timeout, or process exit. Replaces manual poll loops — a single call blocks until an event fires.

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

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

## Documentation

## What the smart-terminal MCP server does

The smart-terminal MCP server exposes persistent pseudo-terminal sessions to MCP-capable AI clients. A session keeps its working directory, environment, and running processes between tool calls, allowing an agent to continue work instead of starting a new shell for every command. PTY behavior is intended for interactive programs such as REPLs, installers, prompts, and editors that may not work correctly with piped standard input.

The server supports Windows, Linux, and macOS shell workflows. Shell selection is automatic: Windows prefers PowerShell Core, then Windows PowerShell, then Command Prompt; Linux and macOS use `$SHELL`, then Bash, then `sh`.

## How it works

An agent starts a session with `terminal_start`, then can execute commands, write raw input, send special keys, and read buffered output. `terminal_exec` adds completion markers so the server can identify when a command finishes and reports the current working directory. For commands that should not use a shell, `terminal_run` accepts a command and argument list with shell execution disabled.

Output handling is designed for repeated terminal work. `terminal_read` can return only bytes emitted after a supplied position, while `terminal_get_history` retrieves earlier output without consuming it. `terminal_wait` and `terminal_watch` wait for output patterns or other session events instead of requiring repeated polling. Long-running calls may emit best-effort progress notifications when the MCP client supplies a progress token.

## Tools and capabilities

The smart-terminal MCP server provides tools for:

- Starting, listing, resizing, and stopping named terminal sessions.
- Executing interactive or one-shot commands.
- Writing terminal input, sending keys such as Ctrl+C and Tab, and writing files directly.
- Reading output incrementally, retrieving rolling history, or waiting for patterns and quiet periods.
- Paging read-only command output, retrying commands, and comparing two command results with a bounded unified diff.
- Capturing a recent snapshot or saving a full transcript when stopping a session.

Large output from interactive reads and executions is normally reduced to the beginning and end. Paged execution returns a page of lines instead. The meta-tool `terminal_extra` exposes schemas and calls for less frequently used tools.

## Limitations and notes

This server does not compress command output. Its token-related benefits come from returning selected portions of output, reading incrementally, waiting on events, and saving transcripts outside the MCP response. Progress notifications are status updates rather than a full stdout stream, and whether they appear depends on the client.

`terminal_run` is intended for predictable automation but does not support shell built-ins such as `cd` or `dir`. The server supports up to 10 concurrent sessions and includes idle cleanup. On Unix, stopping a session terminates its complete process group to reduce the chance of orphaned child processes. If an AI client already offers a stable interactive, stateful terminal with suitable output handling, this server may not be necessary for basic command execution.

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