Shell Session

Persistent interactive shell sessions for MCP agents.

This MCP server gives MCP-capable AI clients a PTY-backed terminal session that can stay alive across multiple tool calls. It is for interactive or stateful terminal work: SSH logins that prompt for credentials, REPLs, custom terminal programs, long-running dev servers, prompt/response workflows, special keys, and session state that must carry across steps.

For ordinary non-interactive commands, prefer your client or system command-line execution tool. This server can run one-shot commands, but its main purpose is controlled interactive shell work.

This project is a fork and rename of pungggi/smart-terminal-mcp. See NOTICE and LICENSE for attribution and license details.

See CHANGELOG.md for release notes.

Interface

The server registers exactly one MCP tool:

shell_session

The tool input is:

{
  "action": "help",
  "args": {}
}

Use action=help first when the caller is unsure what to do:

{ "action": "help" }

That returns a compact action catalog in content[0].text as a JSON string. To see detailed arguments and examples for selected actions:

{ "action": "help", "args": { "actions": ["start", "write", "read"] } }

There is no schema action and no legacy multi-tool mode. Detailed usage is provided through help.

When To Use It

Good use cases:

• Start an SSH login and respond to prompts.
• Drive a REPL such as Python, Node, database shells, or app-specific consoles.
• Interact with terminal programs that expect typed input over time.
• Start a dev server, wait for readiness text, then keep reading logs.
• Send Ctrl+C, Enter, Tab, Escape, or terminal resize events.
• Keep working directory, environment, and process state across steps.

Poor use cases:

• Simple commands like git status, npm test, dir, or ls when your client already has a command execution tool.
• One-shot scripts where no persistent terminal state or interaction is needed.

Actions

Action	Purpose
help	Show the action list or detailed help for selected actions.
start	Start a persistent terminal session.
exec	Run a command in the original session shell; not for SSH/REPL subshells.
run	Run a one-shot non-interactive command. Prefer the client/system command tool for ordinary cases.
run_paged	Run a read-only command and return one page of output.
write	Send text or template input to a session.
read	Read new output from a session.
get_history	Read previous output from a session history.
resize	Resize a terminal session.
send_key	Send a special key such as Ctrl+C, Enter, Tab, or Escape.
wait	Wait until session output matches a regular expression.
watch	Wait for one of several trigger patterns in session output.
retry	Retry a session command with bounded backoff.
diff	Run two session commands and return a unified diff.
stop	Stop a session, optionally returning a snapshot or writing a transcript.
list	List active sessions.
write_file	Write content to a file relative to the session working directory.

Tool Results

Successful structured payloads are returned as JSON strings in MCP content[0].text, which keeps the response compatible with clients that consume standard text content:

{
  "content": [
    {
      "type": "text",
      "text": "{\"usage\":\"...\",\"actions\":[...]}"
    }
  ]
}

The model is expected to read that JSON text and decide the next shell_session call. Error results are also returned as text with isError: true.

Common Workflows

Start And Use A Session

{ "action": "start", "args": { "name": "main" } }

Then run a command inside that session:

{ "action": "exec", "args": { "sessionId": "calm-reef", "command": "pwd" } }

exec wraps commands for the shell that started the session so it can detect completion, exit code, and working directory. Do not use it after entering an interactive subshell such as SSH, Python, Node, a database shell, or a container shell. In those contexts the remote or nested shell may not understand the wrapper commands, and the session can remain busy waiting for markers that will never be emitted. Use write, read, wait, and watch instead.

Interactive REPL

{ "action": "start", "args": { "name": "python" } }

{ "action": "write", "args": { "sessionId": "calm-reef", "data": "python3\r" } }

{ "action": "read", "args": { "sessionId": "calm-reef" } }

Long-Running Dev Server

{ "action": "start", "args": { "name": "dev-server" } }

{ "action": "write", "args": { "sessionId": "calm-reef", "data": "npm run dev\r" } }

The write response includes position, the absolute output byte position captured before the input was written. Pass that value as wait.since to match only output produced after this write, including output that arrives before the wait call is made.

{ "action": "wait", "args": { "sessionId": "calm-reef", "pattern": "listening on port \\d+", "since": 5000, "timeout": 60000 } }

Watch Logs Without Polling

When watch follows a write, pass the position returned by write as watch.since. That position is captured before the input is written, so watch can still match output that arrives after write but before the watch call starts.

{
  "action": "watch",
  "args": {
    "sessionId": "calm-reef",
    "since": 5000,
    "triggers": [
      { "id": "ready", "pattern": "listening on port", "isRegex": false },
      { "id": "error", "pattern": "ERROR|FATAL", "isRegex": true }
    ],
    "timeout": 60000,
    "quietExitMs": 3000
  }
}

Incremental Reads

{ "action": "read", "args": { "sessionId": "calm-reef" } }

If the response includes position: 5000, read only newer output later:

{ "action": "read", "args": { "sessionId": "calm-reef", "since": 5000 } }

Stop With Snapshot Or Transcript

{ "action": "stop", "args": { "sessionId": "calm-reef", "snapshotLines": 20, "transcriptPath": "/tmp/session.log" } }

Template Input

The write action supports type: "text" and type: "template".

type: "text" interprets common escapes such as \r, \n, and \t.

To submit a command or line of terminal input, end it with \r or call send_key with key: "enter". Do not use \n as Enter; this server writes to a PTY, and \r is the portable terminal submit key across PowerShell, pwsh, cmd, Unix shells, and SSH sessions.

type: "template" expands file and environment placeholders server-side before writing to the PTY. This lets callers inject local file/env content without putting the expanded value in the tool arguments or response. It does not prevent the terminal program itself from echoing input.

Supported placeholders:

Placeholder	Meaning
${file:path}	Whole file
${file:path::1}	Line 1
${file:path::1-2}	Lines 1-2
${file:path::1:1-2:3}	Line/column range
${env:NAME}	Environment variable
$${file:path}	Literal ${file:path}

Line and column numbers are 1-based and inclusive. Relative paths are resolved from the session working directory.

Example:

{
  "action": "write",
  "args": {
    "sessionId": "calm-reef",
    "type": "template",
    "data": "${file:info.txt::2}\r"
  }
}

Output Control

Use these actions when terminal output is large or long-running:

• read with since to avoid re-reading old output.
• wait with since from a prior write to avoid matching older output.
• wait with returnMode: "match-only" when only a match result matters.
• watch to avoid manual poll loops while waiting for log patterns.
• get_history to revisit previous output without dumping the whole buffer.
• stop with transcriptPath to write full history to disk.
• run_paged for large read-only command output.

Structured Parsers

The run action can parse a small set of read-only command signatures:

• git status --porcelain=v1 --branch
• git status --short and git status --short --branch
• git log --oneline
• git branch, git branch -vv, git branch --all, git branch --remotes, git branch --show-current
• git rev-parse --abbrev-ref HEAD, git rev-parse --show-toplevel, git rev-parse --is-inside-work-tree
• git diff --name-only, git diff --name-status, git diff --stat, git diff --shortstat
• git remote -v
• git ls-files
• tasklist /fo csv /nh
• where <name> / which <name>

Use parseOnly: true to omit raw output when structured parsing succeeds. Use summary: true when counts or compact summaries are more useful than raw text.

The run_paged action supports summary: true for read-only commands: git (branch, diff, log, ls-files, remote, rev-parse, status), tasklist, where, and which.

Installation

Run the stable npm release:

npx @pkgpub/shell-session-mcp@stable

Or install globally:

npm install -g @pkgpub/shell-session-mcp

Or clone for development:

git clone https://github.com/CarefulDeveloper/shell-session-mcp.git
cd shell-session-mcp
npm install
npm test

MCP Client Configuration

npm

{
  "mcpServers": {
    "shell-session": {
      "command": "npx",
      "args": ["-y", "@pkgpub/shell-session-mcp@stable"]
    }
  }
}

Local Checkout

{
  "mcpServers": {
    "shell-session": {
      "command": "node",
      "args": ["F:\\VSWorkSpace\\AICoding\\smart-terminal-mcp\\src\\index.js"]
    }
  }
}

Claude Code

claude mcp add shell-session -- npx -y @pkgpub/shell-session-mcp@stable

Architecture

src/
  index.js            MCP server bootstrap, initialize instructions, graceful shutdown
  tools.js            Single shell_session tool, action registry, help, schemas, handlers
  command-runner.js   One-shot command execution used by run/run_paged
  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 management
  session-tools.js    Retry and diff helpers for session commands
  regex-utils.js      Shared regex validation and compilation
  session-id.js       Human-readable session ID generation
  session-manager.js  Session lifecycle, TTL cleanup, concurrency limits
  shell-detector.js   Cross-platform shell auto-detection
  ansi.js             ANSI escape code stripping

Development

npm test

For local MCP debugging, point your client at src/index.js with node; publishing to npm is not required.

License

MIT. This fork preserves the upstream MIT license and attribution; see LICENSE and NOTICE.