pty-mcp

pty-mcp — Interactive PTY Sessions

pty-mcp gives AI agents a stateful terminal: directory changes, environment variables, and running processes persist across tool calls.

Core Tools

Tool	Description
create_local_session	Start a local shell (bash, python3, node…)
create_ssh_session	SSH to a remote host
create_serial_session	Connect to a serial port device
send_input	Send a command, wait for output to settle
read_output	Read output; optionally wait for a regex pattern
send_secret	Prompt the human for a password via GUI dialog (never exposed to AI)
send_control	Send ctrl+c, ctrl+d, arrow keys, tab…
detach_session	Disconnect but keep remote PTY running (ai-tmux)
list_sessions	List active sessions
close_session	Terminate a session

Common Patterns

SSH + sudo password

create_ssh_session(host: "server", user: "admin")
send_input(session_id, "sudo apt update")
read_output(session_id, wait_for: "password")
send_secret(session_id, prompt: "sudo password:")   # GUI dialog, AI never sees it
read_output(session_id, wait_for: "\\$", timeout: 60)

Wait for process to finish

send_input(session_id, "make build")
read_output(session_id, wait_for: "Build complete|Error", timeout: 300, tail_lines: 20)

Persistent session (survives disconnect)

create_ssh_session(host: "server", user: "admin", persistent: true)
send_input(session_id, "./run-migration.sh")
detach_session(session_id)   # safe to disconnect, script keeps running
# later: reattach with create_ssh_session(..., session_id: "existing-id")

Serial / network device

create_serial_session(port: "/dev/ttyUSB0", baud: 9600)
read_output(session_id, wait_for: ">")
send_input(session_id, "show version")

Important Rules

• send_secret: Only call when the session is actively waiting for password input (echo off). Do NOT call on an idle shell prompt.
• wait_for: Always set a timeout for long-running commands. Use tail_lines to get context on timeout.
• Persistent sessions: Require ai-tmux daemon on the remote server.