pty-mcp 是一个 MCP（模型上下文协议）服务器，为 AI 智能体提供交互式终端会话，支持本地 shell、SSH、串口以及可在断开连接后继续存在的持久化远程会话。根据仓库说明，它是为希望借助 AI 完成真实服务器与设备管理（而非仅代码生成）的系统管理员和网络工程师构建的。
用途与背景 AI 智能体通常在非交互式 shell 中运行命令，因此无法：SSH 登录服务器并与运行中的进程交互；通过串口控制台连接路由器或交换机；监控日志并在特定事件发生时作出反应；跨多条命令保持会话状态；等待服务器重启并检测其何时恢复。pty-mcp 通过 MCP 提供真实 PTY 会话以解决上述问题。仓库还提到，没有 pty-mcp 时，AI 智能体只能使用 sleep 30 && check_status 之类的循环，浪费 CPU 周期和 API 调用；使用 wait_for 后，智能体在服务端阻塞直到事件发生，从而减少轮询。
主要能力 项目列出的典型场景包括：服务器管理、网络设备管理、日志监控与告警、可在断开后继续的长时间运行任务。已注册的 MCP 工具示例涵盖：本地交互式 shell；SSH 到远程服务器；wait_for 模式等待（v0.2.0）；发送机密/密码 send_secret（v0.3.0）；持久化会话（在 SSH 断开后存活）。
安装与使用方式 仓库提供多种安装途径：
- Claude Code 插件（推荐）：自动安装二进制文件并注册 MCP 服务器，无需手动执行 claude mcp add。重启 Claude Code 后，二进制文件会在会话启动时自动下载，然后再次重启以激活。更新时同样重启，新二进制文件自动下载，再次重启以应用更新。
- macOS / Linux / WSL2 一行安装并注册，重启 Claude Code 后即可使用工具。
- 从 GitHub Releases 下载对应平台的二进制文件并使其可执行。
- 从源码构建（需要 Go 1.25+）。
- WSL2 开箱即用，使用 Linux 二进制文件。
- 可选：在远程服务器安装 ai-tmux，以实现 SSH 断开后仍存活的持久会话。
ai-tmux：持久终端守护进程 ai-tmux 是运行在远程服务器上的轻量守护进程，可在 SSH 断开时保持 PTY 会话存活，仓库将其描述为“为 AI 智能体设计的 tmux”。其模式包括：ai-tmux server（守护进程模式，监听 Unix socket，管理 PTY 会话）、ai-tmux client（桥接模式，通过 stdin/stdout 转发 JSON 协议，由 pty-mcp 经 SSH 使用）、ai-tmux list（列出现有会话）。当 pty-mcp 以 persistent: true 连接时，守护进程会自动启动；会话在空闲 30 分钟后被回收。pty-mcp 在打开会话前会检查远程主机上的 ai-tmux --version，若二进制文件缺失或低于所需最低版本会返回明确错误，而不是晦涩的连接错误。
send_secret 的平台支持与行为 仓库说明了 send_secret 的平台差异：macOS 使用原生密码对话框（osascript）；WSL2 使用 powershell.exe Get-Credential（Windows GUI 对话框）；带显示服务器的 Linux 使用 zenity 或 kdialog；无头 Linux 回退到 /dev/tty。在 macOS/Linux 上，如果操作者 60 秒内未响应，对话框被关闭，调用返回超时错误，而不会进入另一个对话框或再次等待；取消调用（例如在 Claude Code 中按 ESC）会以同样方式立即关闭对话框。WSL2 是例外：其对话框没有超时，且从不被强制关闭，包括取消时也不关闭——因为终止一个由 WSL 互操作启动、持有已打开 Windows GUI 窗口的进程，会导致宿主终端冻结（无法输入、滚动和选择），直到操作者关闭该终端，且除此之外无法恢复。该对话框只会等待操作者自行回答或点击取消，随后正常退出。
审计日志功能 pty-mcp 包含可选的审计日志功能，将每个 send_input 命令记录到中央收集器，便于团队审查和追踪 AI 智能体在会话期间的操作。仓库强调这是自愿的自报操作日志，依赖操作者主动启用并运行收集器；由于 pty-mcp 运行在操作者自己的机器上，没有技术机制强制记录，不合规的操作者可以完全不启用审计运行 pty-mcp。该功能为需要的团队提供可追溯性，但在有审计合规要求的环境中，不能替代系统级审计工具（如 auditd、syslog 转发、SSH 会话录制）。 记录内容包括：时间戳、操作者身份、会话 ID、会话类型（local/ssh/serial）、目标主机；通过 send_input 发送的确切输入（包括 raw=true 的输入，如菜单选择）；每条命令后的输出片段（前 2 KB）；将命令与其输出关联的 cmd_id。send_secret 从不被记录——通过 GUI 对话框输入的机密不会出现在审计日志中。命令和输出片段在写入前会自动脱敏，以下模式会被替换为 [REDACTED] 或 [PRIVATE KEY REDACTED]：键值凭据（password=、passwd:、token=、api_key=、access_key=、auth_token=、secret=）；HTTP Authorization 头（Authorization: Bearer …、Authorization: Basic …、Authorization: Token …）；PEM 私钥块（-----BEGIN RSA PRIVATE KEY----- / -----BEGIN OPENSSH PRIVATE KEY-----）。
配置与运行 每位操作者运行一次以创建配置并生成令牌：这会创建 ~/.config/pty-mcp/config（chmod 600），其中包含随机生成的令牌，并打印令牌以分享给收集器管理员。收集器管理员使用 init 输出中的令牌启动服务器。启用审计需在配置中设置收集器 URL。若要临时停止日志记录而不丢失配置，可进行相应操作。没有配置文件的操作者不受影响——审计默认关闭。日志以 JSONL（每行一个 JSON 对象）存储，可用标准工具读取。
其他说明 pty-mcp 读取 ~/.ssh/config 以解析主机别名。串口需要适当的设备权限；持久会话需要远程服务器上的 ai-tmux 二进制文件。版本历史见 CHANGELOG.md。
