Pty MCP

What raychao-oao/pty-mcp does

raychao-oao/pty-mcp gives MCP-compatible AI agents access to interactive pseudo-terminals instead of one-shot command execution. It can open a local shell or interpreter, connect to a remote host through SSH, or attach to a serial device such as a router, switch, embedded system, or other hardware console.

The server is suited to workflows that require session state and live interaction: entering commands into a REPL, interrupting a running process, watching a log until a pattern appears, waiting for a reboot to complete, or running a task that must continue after the agent disconnects. Its send_secret operation displays a native prompt for the human operator and sends the entered value directly to the PTY; the secret is not returned to the AI context or written to logs.

How it works

The server runs as a single Go executable and exposes its MCP interface through JSON-RPC over stdio. A session manager maintains local, SSH, serial, and remote persistent session types. Local PTYs use the host system, SSH sessions use remote PTYs, and serial sessions communicate with a selected device port.

Output can be read after it settles or held until a regular-expression pattern appears. wait_for accepts a timeout and can return surrounding context or only the most recent lines, which supports log monitoring and long waits without repeated sleep-and-check calls. Session output uses bounded buffering to avoid unbounded memory growth during long-running activity.

Persistent mode connects over SSH to ai-tmux, whose remote daemon owns the PTY. Detaching the MCP session leaves that remote process running; a later session can list and reattach to it. Terminal dimensions can be changed for local, SSH, serial, and persistent sessions.

Setup and configuration

Claude Code can install the binary and register the MCP server through the project’s plugin marketplace:

claude plugin marketplace add raychao-oao/pty-mcp
claude plugin install pty-mcp@pty-mcp

After installation, Claude Code must be restarted twice: once for the binary download and again to activate it. Updates use claude plugin marketplace update pty-mcp followed by claude plugin update pty-mcp@pty-mcp, with the same restart sequence.

A manual installation is also available for macOS, Linux, and WSL2. The installation script can place the executable at /usr/local/bin/pty-mcp, after which it can be registered with:

claude mcp add pty-mcp -- /usr/local/bin/pty-mcp

Release binaries are provided for macOS Apple Silicon, macOS Intel, Linux x86_64, and Linux ARM64. Building from source requires Go 1.25 or later. Persistent remote sessions additionally require the ai-tmux binary on the target host.

Tools and capabilities

• create_local_session starts an interactive local terminal, including bash, Python, or Node sessions.
• create_ssh_session opens an SSH PTY, supports SSH config aliases, and can request persistent mode.
• create_serial_session connects to a serial port with a selected baud rate.
• send_input writes commands or interaction text and waits for output to settle.
• read_output reads buffered output and can wait for a pattern with timeout, context-line, and tail-line options.
• send_control sends control characters and terminal keys such as Ctrl-C, Ctrl-D, arrows, Tab, and Escape.
• send_secret collects a value through a native GUI prompt and sends it without exposing the value to the AI.
• list_sessions, close_session, detach_session, and resize_session manage active sessions.
• list_remote_sessions finds persistent sessions on a remote host.

Optional audit logging can record send_input operations for review. Credentials, authentication headers, and PEM keys are redacted before being written to that log.

Limitations and notes

Persistent sessions depend on installing and running ai-tmux on the remote server. The documented installation flow targets macOS, Linux, and WSL2, with platform-specific release binaries. send_secret requires a supported native dialog environment, including macOS system dialogs, Windows credential prompts through WSL2, or Linux zenity/kdialog.