Pty MCP

What raychao-oao/pty-mcp MCP server does

raychao-oao/pty-mcp MCP server gives an AI agent access to interactive pseudo-terminal sessions rather than one-off non-interactive command execution. It can start local sessions for shells and interpreters such as bash, Python, or Node.js; open SSH sessions to remote hosts; and connect to serial devices used by embedded or network equipment.

The server is aimed at operational work where commands may prompt for input, produce output over time, or require terminal control. An agent can start a process, send additional input, interrupt it, wait for a known output pattern, and inspect recent output. Examples supported by the project include checking whether a rebooted host is reachable, watching a log until an error appears, and interacting with a router console.

How it works

The server communicates with an MCP client over JSON-RPC on standard input and output. A session manager maintains the active terminal sessions and returns session identifiers that subsequent tool calls use.

Local terminals use a PTY on the machine running the server. SSH sessions create remote PTYs and support SSH configuration aliases. Serial sessions connect to a specified device and baud rate. For persistent remote work, the SSH connection can use ai-tmux on the remote host; the remote PTY then remains available after the client disconnects and can be reattached later.

Output handling includes settle detection and optional regular-expression matching. read_output can wait for a pattern, apply a timeout, and return surrounding or trailing lines. A bounded ring buffer is used for long-running sessions. send_secret opens a native operator prompt and sends the entered value directly to the PTY; the agent receives only success and length information according to the provided example.

Setup and configuration

The project is distributed as a Go binary. The README documents a Claude Code plugin that installs the binary automatically, a shell installer for macOS, Linux, and WSL2, downloads from GitHub Releases, and building with Go 1.25 or newer. Manual registration uses the installed pty-mcp executable with the client’s MCP configuration.

Persistent sessions require an ai-tmux binary on the remote server. It can be installed there with the project’s installer or copied to the host. Without that remote component, regular local, SSH, and serial sessions remain available, but the documented persistent-session workflow is not.

No required environment variables or paid API credentials are documented. SSH access, serial-device permissions, local GUI support for secret prompts, and access to the target hosts or devices depend on the deployment environment.

Tools and capabilities

The exposed tools cover:

• Creating local, SSH, and serial sessions.
• Sending input and control keys such as interrupt, end-of-input, arrows, tab, and escape.
• Reading output immediately or waiting for a pattern with timeout and context options.
• Sending operator-entered secrets without returning the secret to the AI context.
• Listing, closing, detaching, resizing, and reattaching sessions.
• Listing persistent sessions on a remote host.

An optional audit log can record send_input operations to a collector. The documented redaction behavior removes credentials, authentication headers, and PEM keys before audit entries are written.

Limitations and notes

The server operates real local terminals, remote shells, and device consoles, so the MCP host and its user account need appropriate operating-system, SSH, and serial permissions. Secret entry depends on a supported graphical prompt: the README names macOS system dialogs, Windows credential prompts under WSL2, and zenity or kdialog on Linux.

Persistent remote sessions are a separate capability from ordinary SSH sessions and depend on ai-tmux being available on the destination host. The README describes supported release binaries for macOS and Linux platforms and specifically documents WSL2 usage; it does not establish support for every operating system or MCP client.

raychao-oao/pty-mcp MCP server is therefore best suited to controlled administration, device operations, interactive troubleshooting, and long-running tasks where an agent must preserve terminal state instead of repeatedly polling a non-interactive command.