Smart Terminal

smart-terminal-mcp

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

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 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):

{

"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:

"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:

"env": {

"SMART_TERMINAL_DISABLED_TOOLS": "terminal_exec,terminal_diff,terminal_retry,terminal_resize,terminal_send_key,terminal_write,terminal_read,terminal_get_history,terminal_watch" }

7 core tools + terminal_extra holding 9 tools on demand.

Installation

Recommended: run the stable release directly via npx:

npx smart-terminal-mcp@stable

Or install globally:

npm install -g smart-terminal-mcp

Or clone for development:

git clone <repo-url>

cd smart-terminal-mcp npm install

Configuration

Shell selection

Set SMART_TERMINAL_SHELL to a shell name or absolute path to pin the shell used by terminal_start when its shell parameter is omitted. This keeps command syntax and startup behavior consistent across MCP clients and server restarts.

"env": {

"SMART_TERMINAL_SHELL": "pwsh" }

Shell selection follows this precedence:

1. Explicit parameter: terminal_start({ shell }) overrides environment settings.
2. Generic pin: SMART_TERMINAL_SHELL applies on Windows, Linux, and macOS.
3. Legacy override: PWSH_PATH remains available on Windows.
4. Auto-detection: The existing platform-specific order applies when no usable pin is set.

An unavailable SMART_TERMINAL_SHELL value is ignored, allowing legacy or platform detection to continue.

Startup arguments match the selected shell:

• PowerShell (`pwsh` / `powershell`): Explicit and pinned sessions start with -NoLogo -NoProfile. Windows auto-detection uses the same flags.
• Other shells: cmd, bash, zsh, fish, and sh start without added arguments.

This prevents PowerShell profiles, aliases, and prompt customization from changing automation behavior between machines.

Claude Desktop

Add to your claude_desktop_config.json:

{

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

Claude Code

claude mcp add smart-terminal -- npx -y smart-terminal-mcp@stable

Augment Code

Add to your Augment MCP settings:

{

"mcpServers": { "Sma