pty-mcp

pty-mcp is an MCP (Model Context Protocol) server that provides AI agents with interactive terminal sessions, supporting local shells, SSH, serial ports, and persistent remote sessions that can continue to exist after disconnection. According to the repository description, it is built for system administrators and network engineers who want to use AI to accomplish real server and device management (rather than just code generation).

Purpose and Background AI agents usually run commands in non-interactive shells, so they cannot: SSH into a server and interact with running processes; connect to a router or switch through a serial console; monitor logs and react when specific events occur; maintain session state across multiple commands; wait for a server to restart and detect when it recovers. pty-mcp solves the above problems by providing real PTY sessions through MCP. The repository also mentions that without pty-mcp, AI agents can only use loops like sleep 30 && check_status, wasting CPU cycles and API calls; with wait_for, the agent blocks on the server side until an event occurs, thereby reducing polling.

Main Capabilities The typical scenarios listed by the project include: server management, network device management, log monitoring and alerting, and long-running tasks that can continue after disconnection. Examples of registered MCP tools cover: local interactive shell; SSH to a remote server; wait_for pattern waiting (v0.2.0); sending secrets/passwords send_secret (v0.3.0); persistent sessions (surviving after SSH disconnection).

Installation and Usage The repository provides multiple installation methods:

1. Claude Code plugin (recommended): automatically installs the binary and registers the MCP server, with no need to manually run claude mcp add. After restarting Claude Code, the binary will be automatically downloaded when the session starts, then restart again to activate. When updating, likewise restart, the new binary will be automatically downloaded, and restart again to apply the update.
2. One-line installation and registration on macOS / Linux / WSL2, and the tools can be used after restarting Claude Code.
3. Download the binary for the corresponding platform from GitHub Releases and make it executable.
4. Build from source (requires Go 1.25+).
5. WSL2 works out of the box, using the Linux binary.
6. Optional: install on a remote server ai-tmux, to achieve persistent sessions that survive SSH disconnection.

ai-tmux: persistent terminal daemon ai-tmux is a lightweight daemon running on a remote server that keeps PTY sessions alive when SSH disconnects; the repository describes it as "tmux designed for AI agents." Its modes include: ai-tmux server (daemon mode, listening on a Unix socket, managing PTY sessions), ai-tmux client (bridge mode, forwarding the JSON protocol over stdin/stdout, used by pty-mcp over SSH), and ai-tmux list (listing existing sessions). When pty-mcp connects with persistent: true, the daemon starts automatically; sessions are reclaimed after 30 minutes of idle time. Before opening a session, pty-mcp checks ai-tmux --version on the remote host; if the binary is missing or below the required minimum version, it returns a clear error rather than an obscure connection error.

Platform support and behavior of send_secret The repository documents the platform differences of send_secret: macOS uses a native password dialog (osascript); WSL2 uses powershell.exe Get-Credential (a Windows GUI dialog); Linux with a display server uses zenity or kdialog; headless Linux falls back to /dev/tty. On macOS/Linux, if the operator does not respond within 60 seconds, the dialog is closed, and the call returns a timeout error rather than opening another dialog or waiting again; canceling the call (for example, pressing ESC in Claude Code) closes the dialog immediately in the same way. WSL2 is the exception: its dialog has no timeout and is never forcibly closed, including on cancellation—because terminating a process launched by WSL interoperability that holds an open Windows GUI window causes the host terminal to freeze (no input, scrolling, or selection) until the operator closes that terminal, and it cannot be recovered otherwise. The dialog only waits for the operator to answer it themselves or click cancel, and then exits normally.

Audit logging feature pty-mcp includes an optional audit logging feature that records every send_input command to a central collector, making it easy toTeams review and track an AI agent's actions during a session. The repository emphasizes that this is a voluntary self-reported operation log, relying on the operator to proactively enable and run the collector; because pty-mcp runs on the operator's own machine, there is no technical mechanism to enforce logging, and a non-compliant operator can simply run pty-mcp without enabling auditing at all. This feature provides traceability for teams that need it, but in environments with audit compliance requirements, it cannot replace system-level auditing tools (such as auditd, syslog forwarding, SSH session recording). The recorded content includes: timestamp, operator identity, session ID, session type (local/ssh/serial), target host; the exact input sent via send_input (including input with raw=true, such as menu selections); the output snippet after each command (the first 2 KB); the cmd_id that associates a command with its output. send_secret is never recorded—secrets entered through the GUI dialog will not appear in the audit log. Commands and output snippets are automatically redacted before being written, and the following patterns are replaced with [REDACTED] or [PRIVATE KEY REDACTED]: key-value credentials (password=, passwd:, token=, api_key=, access_key=, auth_token=, secret=); HTTP Authorization headers (Authorization: Bearer …, Authorization: Basic …, Authorization: Token …); PEM private key blocks (-----BEGIN RSA PRIVATE KEY----- / -----BEGIN OPENSSH PRIVATE KEY-----).

Configuration and Operation Each operator runs it once to create the configuration and generate a token: this creates ~/.config/pty-mcp/config (chmod 600), which contains a randomly generated token, and prints the token to share with the collector administrator. The collector administrator starts the server using the token from the init output. Enabling auditing requires setting the collector URL in the configuration. To temporarily stop logging without losing the configuration, perform the corresponding action. Operators without a configuration file are unaffected—auditing is off by default. Logs are stored as JSONL (one JSON object per line) and can be read with standard tools.

Other Notes pty-mcp reads ~/.ssh/config to resolve host aliases. Serial ports require appropriate device permissions; persistent sessions require the ai-tmux binary on the remote server. For version history, see CHANGELOG.md.