pty-mcp
Enables programmatic control of a Node.js REPL session, allowing execution of JavaScript code and commands via sentinel-based completion detection.
Enables programmatic control of a Python REPL session, allowing execution of Python code and commands via sentinel-based completion detection.
Enables programmatic control of a Ruby (IRB) REPL session, allowing execution of Ruby code and commands via sentinel-based completion detection.
Enables programmatic control of a Zsh shell session, allowing execution of shell commands and scripts via sentinel-based completion detection.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pty-mcp start a bash session and run 'ls -la'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
PTY-MCP
MCP server exposing PTY (pseudo-terminal) sessions for AI agents. Enables programmatic control of shell sessions and REPLs through the Model Context Protocol.
Features
Start and manage multiple PTY sessions
Run commands with sentinel-based completion detection
Works with any shell (bash, zsh, tcsh, fish, etc.)
Works with nested REPLs (Python, Node, Tcl, etc.)
Configurable session timeout and buffer size
Raw input support for interactive applications
Related MCP server: PTY MCP Server
Installation
uv add pty-mcpUsage
As an MCP Server
Add to your MCP client configuration:
{
"mcpServers": {
"pty": {
"command": "uv",
"args": ["run", "pty-mcp"]
}
}
}Or run directly:
uv run pty-mcp --max-sessions 10 --log-dir /path/to/logsThe --log-dir option enables real-time session logging. When specified, each session's output is written immediately to a log file named pty_<command_name>_<session_id>.log (e.g., pty_bash_3a4b5c6d7e8f.log). The directory must exist; the server will error if it doesn't. You can watch logs in real-time with tail -f /path/to/logs/*.log.
MCP Tools
start_session
Start a new PTY session with any command or shell.
Parameters:
command(optional): Command/binary to execute (default:$SHELLor/bin/bash). Can be any executable likebash,python3,tcl,somebinary -a -b, etc. Ifargsis not provided, the command string will be automatically parsed to extract arguments.args(optional): List of arguments to pass to the command. If omitted, arguments will be parsed from thecommandstring. Explicitly provide this when arguments contain spaces or special characters.cwd(optional): Working directorytimeout_session(optional): Idle timeout (default: 86400)buffer_size(optional): Scrollback buffer lines (default: 1000)sentinel_command(optional): Command to echo sentinel (default:echo {sentinel})
Returns: Session ID
Examples:
# Start default shell (bash)
start_session()
# Start Python REPL
start_session(command="python3")
# Start custom binary with arguments (auto-parsed)
start_session(command="somebinary -a -b --args")
# Start with explicit args (for complex arguments)
start_session(command="somebinary", args=["-a", "-b", "--args"])
# Start Tcl shell in specific directory
start_session(command="tclsh", cwd="/path/to/project")run_command
Run a command and wait for completion.
Parameters:
session_id(required): Session ID fromstart_sessioncommand(required): Command to runtimeout(optional): Timeout in seconds (default: 1800)
Returns: Command output
send_keys
Send raw input without waiting for completion.
Parameters:
session_id(required): Session IDkeys(required): Raw input (use\nfor Enter,\x03for Ctrl+C)
get_buffer
Get scrollback buffer contents.
Parameters:
session_id(required): Session IDlines(optional): Number of lines from end
Returns: Buffer contents
stop_session
Stop and clean up a session.
Parameters:
session_id(required): Session ID to stop
set_sentinel
Change the sentinel command for a session. Use when switching between shells/REPLs.
Parameters:
session_id(required): Session IDsentinel_command(required): New sentinel command template with{sentinel}placeholder
list_sessions
List all active sessions with metadata.
Working with REPLs
When switching from a shell to a REPL (or between REPLs), use set_sentinel to update the sentinel command:
# Start with bash (default sentinel: echo {sentinel})
session_id = start_session()
# Run some bash commands
run_command(session_id, "ls -la")
# Switch to Python REPL
send_keys(session_id, "python3\n")
set_sentinel(session_id, "print('{sentinel}')")
# Now run Python commands
run_command(session_id, "print('hello from python')")
run_command(session_id, "2 + 2")
# Exit Python and switch back to bash
send_keys(session_id, "exit()\n")
set_sentinel(session_id, "echo {sentinel}")Common sentinel commands:
Bash/sh/zsh:
echo {sentinel}Python:
print('{sentinel}')Node.js:
console.log('{sentinel}')Tcl:
puts {sentinel}Ruby (irb):
puts '{sentinel}'
Development
# Install dependencies
uv sync
# Run tests
uv run pytest tests/ -vLicense
MIT
Available Tools
7 toolsget_bufferC
Get the scrollback buffer from a PTY session.
Inputs: session_id (required), lines.
list_sessionsA
List all active PTY sessions.
Inputs: no named parameters.
run_commandA
Run a command in a PTY session and wait for completion. Uses sentinel-based detection to know when command finishes.
Inputs: command (required), session_id (required), timeout.
send_keysA
Send raw input to a PTY session without waiting for completion. Use for interactive input, Ctrl+C (send '\x03'), etc.
Inputs: keys (required), session_id (required).
set_sentinelA
Change the sentinel command for a session. Use when switching between shells/REPLs (e.g., from bash to python).
Inputs: session_id (required), sentinel_command (required).
start_sessionA
Start a new PTY session with any command or shell. Returns a session_id to use with other commands.
Inputs: cwd, args, command, buffer_size, +2 more.
stop_sessionB
Stop and clean up a PTY session.
Inputs: session_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clear, distinct purpose: session lifecycle (start, stop, list), command execution, interactive input, output retrieval, and sentinel configuration. No overlaps.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., start_session, get_buffer), making predictions easy.
7 tools is well-scoped for managing PTY sessions, covering creation, interaction, output, and cleanup without excess.
Core lifecycle and interaction are covered, but lacks tools for session details (e.g., size) or resizing, which are minor gaps.
Maintenance
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with terminal environments through multiple concurrent PTY sessions. Supports cross-platform terminal operations including command execution, session management, and real-time communication.2MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage interactive pseudo-terminal (PTY) sessions for programs requiring full terminal emulation like vim, ssh, and interactive REPLs. It provides tools to spawn sessions, send input with escape sequences, and read buffered terminal output.-
- AlicenseNot gradedqualityDmaintenanceProvides a pseudo-terminal (PTY) interface that allows AI agents to interact with command-line tools requiring interactive prompts. It enables agents to autonomously spawn processes, read output, and send inputs for workflows like database migrations and project scaffolding.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with interactive CLI processes via a real PTY, allowing them to send keystrokes, read screen output, and handle interactive prompts.6 npm1MIT