Server data from the Official MCP Registry
MCP PTY server providing AI agents with real interactive terminal access
MCP PTY server providing AI agents with real interactive terminal access
Valid MCP server (1 strong, 1 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.
3 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-pungggi-smart-terminal": {
"args": [
"-y",
"smart-terminal-mcp"
],
"command": "npx"
}
}
}From the project's GitHub README.
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.
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:
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.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.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.
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.
terminal_exec uses unique markers so it can tell when a command has finished.terminal_exec reports the current folder after each command.terminal_write + terminal_read support prompts, REPLs, and other interactive programs without leaving the current session.terminal_wait can pause until specific text appears, such as server listening on port.terminal_retry can re-run flaky commands with bounded backoff and optional output matching.terminal_exec / terminal_wait calls can emit notifications/progress when the client provides a progress token.terminal_exec and terminal_read shorten very large output by returning the beginning and the end.terminal_run_paged returns large read-only output one page at a time instead of sending the full result at once.terminal_diff compares two command results and returns a unified diff.terminal_run executes binaries directly with cmd + args and shell=false for more predictable automation.GIT_PAGER=cat, PAGER=cat), suppresses PowerShell progress output, and sets UTF-8 for cmd.exe on 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.
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.
terminal_run_paged for large read-only output when the agent wants one page of the returned result at a time.maxLines, pageSize, or tailLines when the agent only needs a narrow slice of the output.summary: true or parseOnly: true with terminal_run when the agent benefits more from structured results than raw text.terminal_wait({ returnMode: "match-only" }) when the agent only needs to know whether a pattern appeared.terminal_get_history when the agent needs to revisit earlier output without re-dumping the whole session into the conversation.In practice, this lets agents inspect terminal state more selectively instead of repeatedly dumping large logs back into the conversation.
By default, the 8 most-used tools are registered with full schemas and 7 convenience tools are collected behind a single lightweight terminal_extra meta-tool (~30 tokens instead of ~1,500).
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
Extra tools are not hidden — the agent sees the tool names in the terminal_extra description and can:
terminal_extra({ list: true }) → returns full parameter schemasterminal_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"
}
5 core tools + terminal_extra holding 10 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"
}
7 core tools + terminal_extra holding 8 tools on demand.
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
Add to your claude_desktop_config.json:
{
"mcpServers": {
"smart-terminal": {
"command": "npx",
"args": ["-y", "smart-terminal-mcp@stable"]
}
}
}
claude mcp add smart-terminal -- npx -y smart-terminal-mcp@stable
Add to your Augment MCP settings:
{
"mcpServers": {
"Smart Terminal": {
"command": "npx",
"args": [
"smart-terminal-mcp@stable"
]
}
}
}
If you want to pin an exact release instead of following the stable tag, replace @stable with a version such as @1.0.1.
By default, 8 core tools are registered with full schemas and 7 convenience tools are available on demand via terminal_extra (see Reducing tool definition overhead).
terminal_startStart a new interactive terminal session.
| Param | Type | Default | Description |
|---|---|---|---|
shell | string | auto-detected | Shell executable (e.g. pwsh.exe, bash) |
cols | number | 120 | Terminal width |
rows | number | 30 | Terminal height |
cwd | string | server CWD | Working directory |
name | string | -- | Friendly session name |
env | object | -- | Custom environment variables (e.g. { "NODE_ENV": "test" }) |
Returns: sessionId, shell, shellType, cwd, banner
terminal_execExecute 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.
| Param | Type | Default | Description |
|---|---|---|---|
sessionId | string | required | Session ID |
command | string | required | Command to execute |
timeout | number | 30000 | Timeout in ms (max 10min) |
maxLines | number | 200 | Max output lines before truncation |
Returns: output, exitCode, cwd, timedOut
terminal_runRun 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 PATH/PATHEXT and launches .cmd / .bat wrappers via cmd.exe when needed. Prefer passing the target executable directly as cmd instead of wrapping it in powershell -Command or cmd /c, especially when Windows paths contain spaces. For tools that always exit 0, you can require a specific exit code and/or validate a success regex against a file written by the command.
| Param | Type | Default | Description |
|---|---|---|---|
cmd | string | required | Executable to run |
args | string[] | [] | Argument array passed directly to the executable |
cwd | string | server CWD | Working directory |
timeout | number | 30000 | Timeout in ms |
maxOutputBytes | number | 102400 | Max combined stdout/stderr bytes to capture |
parse | boolean | true | Attempt structured parsing for supported commands |
parseOnly | boolean | false | Drop raw stdout if parsed |
summary | boolean | false | Return a concise summary when supported |
successExitCode | number or null | 0 | Exit code required for success |
successFile | string | -- | Optional file to validate after exit |
successFilePattern | string | -- | Regex that must match successFile |
Returns: ok, cmd, args, cwd, exitCode, timedOut, durationMs, stdout.raw, stdout.parsed, optional stdout.summary, stderr.raw, optional checks, optional hint
terminal_writeWrite raw data to a terminal (for interactive programs). Follow with terminal_read.
| Param | Type | Description |
|---|---|---|
sessionId | string | Session ID |
data | string | Data to write (\r for Enter, \t for Tab) |
terminal_readRead buffered output with idle detection. Large outputs are truncated to head + tail based on maxLines.
| Param | Type | Default | Description |
|---|---|---|---|
sessionId | string | required | Session ID |
timeout | number | 30000 | Hard timeout in ms |
idleTimeout | number | 500 | Return after this many ms of silence |
maxLines | number | 200 | Max output lines |
Returns: output, timedOut
terminal_waitWait for a specific pattern in the output stream. By default, responses return only the last tailLines; use returnMode: "full" for the full matched output or "match-only" to suppress output entirely. If the MCP client sends a progressToken, long-running waits may also emit best-effort notifications/progress updates.
| Param | Type | Default | Description |
|---|---|---|---|
sessionId | string | required | Session ID |
pattern | string | required | String or regex pattern |
timeout | number | 30000 | Timeout in ms |
returnMode | string | "tail" | Response mode: tail, full, match-only |
tailLines | number | 50 | Number of tail lines to return |
Returns: output, matched, timedOut (output may be empty in match-only mode)
terminal_stopStop and clean up a terminal session.
| Param | Type | Description |
|---|---|---|
sessionId | string | Session ID to stop |
terminal_listList all active terminal sessions.
| Param | Type | Default | Description |
|---|---|---|---|
verbose | boolean | true | Include full metadata |
Returns: sessions, count (verbose: false returns id, name, cwd, alive, busy only)
terminal_extra)The following tools are available by default through the terminal_extra meta-tool. The agent can discover their schemas via terminal_extra({ list: true }) and call them via terminal_extra({ tool: "<name>", args: { ... } }).
terminal_extraMeta-tool for discovering and calling extra tools.
| Param | Type | Default | Description |
|---|---|---|---|
list | boolean | false | Return full parameter schemas for all extra tools |
tool | string | -- | Name of the extra tool to call |
args | object | -- | Arguments to pass to the extra tool |
terminal_send_keySend a named special key.
| Param | Type | Description |
|---|---|---|
sessionId | string | Session ID |
key | string | Key name (see below) |
Supported keys: ctrl+c, ctrl+d, ctrl+z, ctrl+l, ctrl+a, ctrl+e, ctrl+u, ctrl+k, ctrl+w, tab, enter, escape, up, down, left, right, home, end, pageup, pagedown, backspace, delete, f1-f12
terminal_run_pagedRun 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 supported read-only commands when summary: true.
| Param | Type | Default | Description |
|---|---|---|---|
cmd | string | required | Read-only executable to run |
args | string[] | [] | Argument array passed directly to the executable |
cwd | string | server CWD | Working directory |
timeout | number | 30000 | Timeout in ms |
maxOutputBytes | number | 102400 | Max combined stdout/stderr bytes to capture |
page | number | 0 | 0-indexed page number |
pageSize | number | 100 | Lines per page |
summary | boolean | false | Return a concise summary when supported |
Returns: Same envelope as terminal_run, plus pageInfo.page, pageInfo.pageSize, pageInfo.totalLines, pageInfo.hasNext
terminal_get_historyRetrieve 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.
| Param | Type | Default | Description |
|---|---|---|---|
sessionId | string | required | Session ID |
offset | number | 0 | Lines to skip from the end (0 = most recent). Use for pagination. |
maxLines | number | 200 | Max lines to return |
format | string | "lines" | Response format: lines or text |
Returns: lines or text, plus totalLines, returnedFrom, returnedTo
terminal_retryRetry a command in the same terminal session until it succeeds or retries are exhausted.
| Param | Type | Default | Description |
|---|---|---|---|
sessionId | string | required | Session ID |
command | string | required | Command to execute |
maxRetries | number | 3 | Retry count after the first attempt |
backoff | string | "exponential" | Backoff mode: fixed, linear, exponential |
delayMs | number | 1000 | Base delay in ms |
timeout | number | 30000 | Timeout per attempt in ms |
maxLines | number | 200 | Max output lines per attempt |
successExitCode | number or null | 0 | Exit code required for success |
successPattern | string or null | null | Optional regex that must match output |
Returns: success, attempts, lastResult, history
terminal_diffRun two commands in the same terminal session and return a bounded unified diff of their outputs.
| Param | Type | Default | Description |
|---|---|---|---|
sessionId | string | required | Session ID |
commandA | string | required | Baseline command |
commandB | string | required | Comparison command |
timeout | number | 30000 | Timeout per command in ms |
maxLines | number | 200 | Max output lines per command |
contextLines | number | 3 | Diff context lines |
Returns: resultA, resultB, diff, identical
terminal_resizeResize terminal dimensions.
| Param | Type | Description |
|---|---|---|
sessionId | string | Session ID |
cols | number | New width |
rows | number | New height |
terminal_write_fileWrite 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.
| Param | Type | Default | Description |
|---|---|---|---|
sessionId | string | required | Session ID (used to resolve working directory) |
path | string | required | File path (relative to session CWD, or absolute) |
content | string | required | File content to write |
encoding | string | "utf-8" | File encoding (utf-8, ascii, base64, hex, latin1) |
append | boolean | false | Append to file instead of overwriting |
Returns: success, path (absolute), size (bytes), append
terminal_start() -> { sessionId: "a1b2c3d4" }
terminal_exec({ sessionId, command: "ls -la" }) -> { output: "...", exitCode: 0, cwd: "/home/user" }
terminal_run({ cmd: "git", args: ["status", "--porcelain=v1", "--branch"] })
-> { ok: true, stdout: { raw: "...", parsed: { branch: {...}, staged: [], modified: [], untracked: [] } } }
For Windows tools installed under Program Files, prefer this shape over powershell -Command:
terminal_run({ cmd: "C:\\Program Files\\Vendor\\Tool.exe", args: ["/flag:value", "/other"] })
For compilers that only report success in a log file:
terminal_run({
cmd: "C:\\Program Files\\Vendor\\Tool.exe",
args: ["/compile:script.mq5", "/log:build.log"],
successFile: "build.log",
successFilePattern: "0 error"
})
terminal_run_paged({ cmd: "git", args: ["log", "--oneline"], page: 0, pageSize: 100 })
-> { ok: true, stdout: { raw: "...", parsed: null }, pageInfo: { totalLines: 120, hasNext: true } }
terminal_start({ name: "python" })
terminal_write({ sessionId, data: "python3\r" })
terminal_read({ sessionId }) -> Python banner
terminal_write({ sessionId, data: "2 + 2\r" })
terminal_read({ sessionId }) -> "4"
terminal_send_key({ sessionId, key: "ctrl+d" }) -> exit Python
terminal_start({ name: "dev-server" })
terminal_write({ sessionId, data: "npm run dev\r" })
terminal_wait({ sessionId, pattern: "listening on port", timeout: 60000 })
terminal_wait({ sessionId, pattern: "listening on port", returnMode: "full" })
terminal_retry({ sessionId, command: "npm test", maxRetries: 2, backoff: "fixed", delayMs: 1000 })
-> { success: true, attempts: 2, lastResult: { output: "...", exitCode: 0, cwd: "...", timedOut: false } }
terminal_diff({ sessionId, commandA: "git show HEAD~1:README.md", commandB: "type README.md" })
-> { identical: false, diff: "--- git show HEAD~1:README.md\n+++ type README.md\n@@ @@\n..." }
src/
index.js Entry point, server bootstrap, graceful shutdown
tools.js MCP tool registrations with Zod schemas
command-runner.js One-shot non-interactive command execution (shell=false)
command-parsers.js Structured parsers for supported read-only commands
pager.js Line-based pagination helper for large stdout
pty-session.js PTY session: marker injection, idle read, buffer mgmt
smart-tools.js Retry and diff helpers for higher-level terminal tools
regex-utils.js Shared user-regex validation and compilation
session-manager.js Session lifecycle, TTL cleanup, concurrency limits
shell-detector.js Cross-platform shell auto-detection
ansi.js ANSI escape code stripping
terminal_run currently parses a small set of read-only command signatures:
git log --onelinegit log --oneline -n <count>git status --porcelain=v1 --branchgit status --short --branchgit status --shortgit branchgit branch --all / git branch --remotesgit branch -vvgit branch --show-currentgit rev-parse --abbrev-ref HEADgit rev-parse --show-toplevelgit rev-parse --is-inside-work-treegit diff --name-onlygit diff --name-statusgit diff --statgit diff --shortstatgit ls-filesgit remote -vtasklist /fo csv /nhwhere <name> / which <name>Set parseOnly: true to omit stdout.raw when a supported parser succeeds. Unsupported commands still return stdout.raw; stdout.parsed is null.
Set summary: true to return stdout.summary and suppress stdout.raw for supported command signatures. If no summary is available, raw stdout is preserved.
terminal_run_paged supports summary: true for read-only commands: git (branch, diff, log, ls-files, remote, rev-parse, status), tasklist, where, and which.
When parsing was requested but no parser matched, terminal_run may include a short hint for parser-worthy command signatures with larger raw output:
git plus where / whichstdout.raw is large enough to be worth suggestingStructured parser unavailable for this command signature. If you need this often, propose one.MIT
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
by mcp-marketplace · Developer Tools
Scaffold, build, and publish TypeScript MCP servers to npm — conversationally
by Taylorwilsdon · Productivity
Control Gmail, Calendar, Docs, Sheets, Drive, and more from your AI