# raychao-oao/pty-mcp [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/raychao-oao/pty-mcp  
**GitHub Stars:** 17  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/raychao-oao-pty-mcp

## Description
Interactive PTY sessions for AI agents — local shells, SSH with persistent sessions (ai-tmux daemon for attach/detach), and serial ports. Single Go binary, no tmux dependency.

## Tools
Capabilities this server exposes over MCP:

- **create_local_session** — Start a local interactive terminal (bash, python3, node, etc.)
- **create_ssh_session** — SSH to a remote host (supports SSH config aliases)
- **create_serial_session** — Connect to a serial port device
- **send_input** — Send a command and wait for output to settle
- **read_output** — Read output, optionally wait for a pattern (`wait_for`, `timeout`, `context_lines`, `tail_lines`)
- **send_control** — Send control keys (ctrl+c, ctrl+d, arrows, tab, etc.)
- **send_secret** — Prompt the human operator for a secret via GUI dialog; sends it to the PTY session without exposing it to AI context or logs ¹
- **list_sessions** — List all active sessions
- **close_session** — Close a session (terminates remote PTY)
- **detach_session** — Disconnect but keep remote PTY running
- **resize_session** — Resize the terminal window (rows/cols) for any session type
- **list_remote_sessions** — List persistent sessions on a remote host

## Claude Desktop Quick Installation
Install path inferred — verify against the README before running it. Uses `go` (confidence: medium):

```json
"mcpServers": {
  "pty-mcp": {
    "command": "go",
    "args": ["run","github.com/raychao-oao/pty-mcp@latest"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/raychao-oao-pty-mcp/readme_