raychao-oao/pty-mcp

An MCP (Model Context Protocol) server that gives AI agents interactive terminal sessions — local shells, SSH, serial ports, and persistent remote sessions that survive disconnects.
Built for **sysadmins and network engineers** who want AI to help with real server and device management, not just code generation.
Why
AI agents run commands in non-interactive shells. They can't:
- SSH into a server and interact with running processes
- Connect to routers or switches via serial console
- Monitor logs and react when a specific event occurs
- Keep session state across multiple commands
- Wait for a server to reboot and detect when it's back up
pty-mcp solves all of these by providing real PTY sessions over MCP.
Without pty-mcp, AI agents resort to sleep 30 && check_status loops — burning CPU cycles and API calls waiting for things to happen. With wait_for, the agent blocks server-side until the event occurs. Less polling, less energy, better for polar bears. 🐻‍❄️
Use Cases
**Server administration**
**Network device management**
**Log monitoring and alerting**
**Long-running tasks that survive disconnects**
Features
| Feature | Description |
|---------|-------------|
| **Local terminal** | Interactive bash/python/node sessions on local machine |
| **SSH sessions** | Connect to remote hosts with key/password auth, SSH config support |
| **Serial port** | Connect to devices via serial (IoT, embedded, network gear) |
| **Persistent sessions** | Sessions survive SSH disconnects via ai-tmux daemon |
| **Attach/Detach** | Detach from a running session, reconnect later |
| **Control keys** | Send ctrl+c, ctrl+d, arrow keys, tab, escape |
| **Settle detection** | Waits for output to settle before returning (smart timeout) |
| **Pattern matching** | wait_for blocks until a regex pattern appears in output (v0.2.0) |
| **Bounded memory** | Ring buffer prevents OOM on long-running sessions (v0.2.0) |
| **Resize terminal** | Resize the PTY window for local, SSH, serial, and persistent remote sessions (v0.10.0) |
| **Audit log** | Optional voluntary operation log — record send_input commands to a collector for review and traceability (v0.8.0) |
| **Audit redaction** | Credentials, auth headers, and PEM keys are automatically scrubbed before being written to the audit log (v0.10.0) |
Architecture
Quick Start
Claude Code Plugin (recommended)
Installs the binary automatically and registers the MCP server:
Restart Claude Code — the binary downloads automatically on session start, then **restart once more** to activate it. No manual claude mcp add needed.
**Updating:**
Restart Claude Code — the new binary downloads automatically on session start, then **restart once more** to apply the update.
Manual install
**One-line install + register** (macOS / Linux / WSL2):
Restart Claude Code and the tools are available.
Other install methods
**Download from GitHub Releases:**
Go to Releases, download the binary for your platform, and make it executable:
| Platform | Binary |
|----------|--------|
| macOS (Apple Silicon) | pty-mcp-darwin-arm64 |
| macOS (Intel) | pty-mcp-darwin-amd64 |
| Linux (x86_64) / WSL2 | pty-mcp-linux-amd64 |
| Linux (ARM64) | pty-mcp-linux-arm64 |
**Build from source** (requires Go 1.25+):
WSL2 Notes
pty-mcp works in WSL2 out of the box. Use the Linux binary:
Optional: Install ai-tmux on remote servers
For persistent sessions that survive SSH disconnects, install ai-tmux on your remote server:
Usage Examples
Once registered, the AI agent can use these MCP tools:
**Local interactive shell:**
**SSH to remote server:**
**Wait for pattern (v0.2.0):**
**Send secret / password (v0.3.0):**
**Persistent session (survives SSH disconnect):**