pty-mcp server

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 && checkstatus loops — burning CPU cycles and API calls waiting for things to happen. With waitfor, the agent blocks server-side until the event occurs. Less polling, less energy, better for polar bears. 🐻‍❄️

Use Cases

Server administration

# Reboot a server and wait until it's back online
create_local_session("ping myserver")
read_output(wait_for: "bytes from", timeout: 300)
→ blocks until server responds after reboot (~80s, one tool call)

Network device management

# Connect to a router via serial console
create_serial_session(port: "/dev/ttyUSB0", baud: 9600)
send_input("show interfaces status")
read_output(wait_for: "\\$")

Log monitoring and alerting

# Watch logs and act when something happens
create_ssh_session(host: "prod", user: "admin")
send_input("tail -f /var/log/app.log")
read_output(wait_for: "ERROR|CRITICAL", timeout: 3600)
→ returns the error line + context when it appears

Long-running tasks that survive disconnects

create_ssh_session(host: "server", user: "admin", persistent: true)
send_input("apt upgrade -y")
detach_session()          → close Claude Code, task continues
# Reconnect later to check result

Features

Architecture

Shortened. The full README is on GitHub.