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

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/raychao-oao/pty-mcp  
**GitHub Stars:** 20  
**Views:** 9  
**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
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

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

```bash
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:

```bash
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`.

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