smart-terminal-mcp

# smart-terminal-mcp
[![Smithery](https://img.shields.io/badge/Smithery-smart--terminal-blue)](https://smithery.ai/server/pungggi/smart-terminal)
[![Official Registry](https://img.shields.io/badge/MCP-Official--Registry-green)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.pungggi/smart-terminal)

A PTY-based MCP server with strong Windows support, giving MCP-capable AI clients and their agents persistent, interactive shell access via pseudo-terminals ([node-pty](https://github.com/microsoft/node-pty)).

Unlike simple `exec`-based approaches, this keeps PTY-backed shell sessions alive across steps, with bidirectional communication for interactive CLI tools, incremental reads, and session state that carries forward.

See the [Changelog](CHANGELOG.md) for recent updates.
## Why use this instead of your AI client's built-in terminal?

Install this if you want a more consistent terminal workflow across AI clients, instead of relying on whatever built-in terminal behavior a single client happens to provide.

This MCP is most useful when you want:

- **Portable workflow across clients** -- The same terminal tools and habits work across Claude Code, Cursor, Trae, Antigravity, and other MCP-capable clients.
- **Reusable prompts and tooling** -- Workflows built around tools like `terminal_wait`, `terminal_retry`, `terminal_run_paged`, and `terminal_get_history` are easier to reuse across teams and clients, with less lock-in to one client's terminal behavior.
- **Persistent terminal state** -- Keep the same shell session alive across steps, including the current folder, environment, and running processes.
- **Better interactive behavior** -- Safely handle tools that expect TTY behavior—such as `vim`, `npm` prompts, or interactive installers that often hang on standard piped stdin. Support full interactive sessions with REPLs, Ctrl+C, arrow keys, and dynamic prompts.
- **More control over large output** -- Truncate, page, diff, retry, wait for patterns, or fetch history instead of dumping everything at once.
- **More predictable automation** -- Use deterministic completion markers instead of guessing when a command is done.

If your AI client already provides a stable, stateful, interactive terminal with good output handling, you may not need this MCP for basic command execution. The main reason to add it is to make terminal-driven workflows more explicit, reusable, and portable across clients.

## Features

Think of this as a **controlled keyboard + terminal for an agent running inside an MCP client**. It opens a persistent PTY-backed shell session so the agent can send commands and keystrokes, read output, and continue working in the same session.

### Core terminal features

- **Interactive terminal sessions** -- Keeps a persistent PTY-backed shell session open so the agent can send input, read output, and pick up where it left off.
- **Deterministic command completion** -- `terminal_exec` uses unique markers so it can tell when a command has finished.
- **Clean output** -- Pre-command markers help keep returned output readable, even when shells echo commands or expand aliases.
- **Working directory tracking** -- `terminal_exec` reports the current folder after each command.

### Long output and long-running commands

- **Interactive reads and writes** -- `terminal_write` + `terminal_read` support prompts, REPLs, and other interactive programs without leaving the current session.
- **Incremental reads** -- `terminal_read` accepts a `since` byte position to return only new output since the last read, avoiding re-reading the full buffer on every poll.
- **Pattern waiting** -- `terminal_wait` can pause until specific text appears, such as `server listening on port`.
- **Event-driven monitoring** -- `terminal_watch` waits for trigger patterns in session output, returning only on match, quiet, timeout, or exit. Eliminates poll-loop token waste.
- **Quiet-exit detection** -- `terminal_exec` can return early when output goes silent (`quietExitMs`), instead of waiting for a hard timeout.
- **Retry helper** -- `terminal_retry` can re-run flaky commands with bounded backoff and optional output matching.
- **Best-effort progress notifications** -- Long `terminal_exec` / `terminal_wait` calls can emit `notifications/progress` when the client provides a progress token.
- **Output truncation** -- `terminal_exec` and `terminal_read` shorten very large output by returning the beginning and the end.
- **Paged read-only output** -- `terminal_run_paged` returns large read-only output one page at a time instead of sending the full result at once.
- **Output diffing** -- `terminal_diff` compares two command results and returns a unified diff.
- **Session snapshots** -- `terminal_stop` can capture a tail snapshot or write a full transcript to disk before stopping.

### Safety and usability

- **Safer one-shot commands** -- `terminal_run` executes binaries directly with `cmd + args` and `shell=false` for more predictable automation.
- **Structured parsers** -- Some supported read-only commands can return both raw text and parsed output.
- **Blocking mitigations** -- Disables pagers (`GIT_PAGER=cat`, `PAGER=cat`), suppresses PowerShell progress output, and sets UTF-8 for `cmd.exe` on Windows.
- **Special key support** -- Can send Ctrl+C, Tab, arrow keys, and similar keys without manually constructing escape sequences.
- **Process group cleanup** -- `terminal_stop` kills the entire process group on Unix, preventing orphan child processes.
- **Session management** -- Supports named sessions, idle cleanup, and up to 10 concurrent sessions. Session IDs are human-readable (e.g. `calm-reef`).
- **Shell auto-detection** -- Windows: `pwsh.exe` > `powershell.exe` > `cmd.exe`. Linux/macOS: `$SHELL` > `bash` > `sh`.

Progress notifications are not the same as full stdout streaming. They currently send periodic status updates for `terminal_exec` and `terminal_wait`, usually based on elapsed time and the latest output line. Whether you see them depends on your MCP client.

## Token efficiency

This MCP does not magically compress terminal output, but it **can help agents use fewer tokens in terminal-heavy workflows** by returning smaller, more targeted responses and making it easier to revisit output only when needed.

The main benefit is **model-context efficiency**, not guaranteed savings in the underlying command's runtime or total bytes produced.

### Polling and long-running processes

- Use **`terminal_read({ since })`** to read incrementally. Each call returns only new output since the last `position`, instead of re-reading the full buffer. Reduces token usage by up to ~87% on repeated polling.
- Use **`terminal_watch`** instead of a manual poll loop when waiting for a specific pattern. A single call returns on match, quiet, timeout, or exit — reduces token usage by up to ~99% for log-watching workflows.
- Use **`terminal_exec({ quietExitMs })`** for long-running commands (dev servers, watchers) that never produce a completion marker. Returns early when output stops, instead of waiting for a hard timeout. Reduces token usage by up to ~94%.

### Output size control

- Use **`terminal_run_paged`** for large read-only output when **the agent** wants one page of the returned result at a time.
- Lower **`maxLines`**, **`pageSize`**, or **`tailLines`** when **the agent** only needs a narrow slice of the output.
- Use **`summary: true`** or **`parseOnly: true`** with `terminal_run` when **the agent** benefits more from structured results than raw text.
- Use **`terminal_wait({ returnMode: "match-only" })`** when the agent only needs to know whether a pattern appeared.
- Use **`terminal_get_history`** when **the agent** needs to revisit earlier output without re-dumping the whole session into the conversation.
- Use **`terminal_stop({ transcriptPath })`** to offload large session history to disk instead of returning it in the response.

In practice, this lets agents inspect terminal state more selectively instead of repeatedly dumping large logs back into the conversation.

### Reducing tool definition overhead

By default, the 8 most-used tools are registered with full schemas and 8 convenience tools are collected behind a single lightweight `terminal_extra` meta-tool (~30 tokens instead of ~1,700).

**Default core tools**: `terminal_start`, `terminal_exec`, `terminal_run`, `terminal_read`, `terminal_write`, `terminal_wait`, `terminal_stop`, `terminal_list`

**Default extra tools** (behind `terminal_extra`): `terminal_run_paged`, `terminal_retry`, `terminal_diff`, `terminal_resize`, `terminal_send_key`, `terminal_get_history`, `terminal_write_file`, `terminal_watch`

Extra tools are **not hidden** — the agent sees the tool names in the `terminal_extra` description and can:

- **Discover schemas**: `terminal_extra({ list: true })` → returns full parameter schemas
- **Call any extra tool**: `terminal_extra({ tool: "terminal_resize", args: { sessionId: "...", cols: 200, rows: 50 } })`

Use `SMART_TERMINAL_DISABLED_TOOLS` to customize which tools are extra, or set it to an empty string to register all 15 tools with full schemas:

**All tools with full schemas** (no meta-tool):

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

**Minimal setup** — only `terminal_exec` for simple command execution:

```json
"env": {
  "SMART_TERMINAL_DISABLED_TOOLS": "terminal_run,terminal_run_paged,terminal_retry,terminal_diff,terminal_write_file,terminal_resize,terminal_send_key,terminal_get_history,terminal_watch"
}
```

5 core tools + `terminal_extra` holding 9 tools on demand.

**Agent-focused setup** -- `terminal_run` instead of `terminal_exec`:

```json
"env": {
  "SMART_TERMINAL_DISABLED_TOOLS": "terminal_exec,terminal_diff,terminal_retry,terminal_resize,terminal_send_key,terminal_write,terminal_rea