pty

pty-mcp-server exposes a MCP interface over stdio that enables AI agents to manage and interact with PTY sessions. Through the built-in tools, an MCP client can start and attach to pseudo-terminal sessions, run interactive shells or CLI tools, and drive terminal-based workflows programmatically. This is particularly useful for automating REPLs, debugging sessions, remote shell access, and orchestrating terminal-driven tasks in a controlled, scriptable manner. The server's PTY-enabled tools ensure that interactive TUI prompts, prompts, and prompts from CLI applications behave as if a human were typing, which is essential for tools that rely on a real TTY to operate correctly. Tools include pty-connect, pty-bash, pty-ssh, and a suite of proc- and socket-based utilities for non-PTY interactions as needed by complex automation pipelines.

Prerequisites:

• Docker installed and running on the host
• Access permissions to run Docker containers

Installation steps:

1. Ensure Docker is available and you can run containers: docker version

2. Pull or build the MCP server image. If using a prebuilt image name matching the repo slug, you can pull by: docker pull phoityne-pty-mcp-server

3. Run the MCP server container in a detached or interactive mode depending on your orchestration needs. Example run (interactive): docker run -it phoityne-pty-mcp-server

4. If your environment requires additional configuration (e.g., logs, debug mode), provide environment variables at runtime. Example: docker run -it -e MCP_LOG=debug phoityne-pty-mcp-server

5. Connect an MCP client to the server via the MCP protocol (stdio-based). The client should start the server process and communicate over standard input/output as defined by MCP.

Note: If you do not have a prebuilt image, you can alternatively build a container from a Dockerfile that installs and runs the Haskell-based pty-mcp-server, then run the container accordingly.

Tips and notes:

• Since the server operates over stdio, ensure your MCP client correctly pipes input and reads output without buffering issues.
• The pty-tools (pty-connect, pty-bash, pty-ssh, etc.) enable interactive operation; prefer PTY-based tools when interacting with TUI applications or commands that require a TTY.
• For remote or long-running sessions, consider using pty-terminate to clean up stuck PTYs.
• If using Docker, map volumes or configure networking as needed for the remote tools (e.g., SSH or Telnet targets).
• Pay attention to security: only expose PTY sessions to trusted MCP clients, as they provide shell-level access to the host system.
• Ensure the host supports the needed shell and utilities (bash, ssh, telnet, etc.) inside the container image for the best compatibility.