pty-mcp

pty-mcp

一个 MCP（Model Context Protocol）服务，为 AI Agent 提供交互式终端会话——本地 Shell、SSH、串行端口，以及断开连接后仍能保持的持久远程会话。

专为系统管理员和网络工程师打造，帮助 AI 管理真实的服务器和设备，而不仅仅是生成代码。

为什么需要

AI Agent 会在非交互式 Shell 中运行命令。它们无法：

• SSH 登录服务器并与正在运行的进程交互
• 通过串行控制台连接路由器或交换机
• 监控日志，并在特定事件发生时作出响应
• 在多条命令之间保留会话状态
• 等待服务器重启，并检测其恢复上线的时间

pty-mcp 通过 MCP 提供真实的 PTY 会话，解决了所有这些问题。

没有 pty-mcp，AI Agent 只能反复执行 sleep 30 && check_status 循环——等待事件发生时白白消耗 CPU 周期和 API 调用。有了 wait_for，Agent 会在服务端阻塞，直到事件发生。减少轮询、降低能耗，也更有利于北极熊。🐻‍❄️

使用场景

服务器管理

# 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)

网络设备管理

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

日志监控和告警

# 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

断开连接后仍能继续运行的长时间任务

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

功能

架构

┌─────────────────────────────────────────────────────┐
│ AI Agent (Claude Code, etc.)                        │
│                                                     │
│  MCP Tools: create_local_session, send_input,       │
│             send_control, read_output, close_session │
└──────────────────────┬──────────────────────────────┘
                       │ JSON-RPC stdio
┌──────────────────────┴──────────────────────────────┐
│ pty-mcp (MCP Server)                                │
│                                                     │
│  Session Manager                                    │
│  ├── LocalSession  (local PTY via creack/pty)       │
│  ├── SSHSession    (remote PTY via x/crypto/ssh)    │
│  ├── SerialSession (serial port via go.bug.st)      │
│  └── RemoteSession (persistent via ai-tmux)         │
└─────────────────────────────────────────────────────┘

Persistent mode (ai-tmux):

  pty-mcp ──SSH──▶ ai-tmux client ──Unix socket──▶ ai-tmux server (daemon)
                                                     ├── PTY: bash
                                                     ├── PTY: ssh admin@router
                                                     └── PTY: tail -f /var/log/syslog

快速开始

Claude Code 插件（推荐）

自动安装二进制文件并注册 MCP 服务：

claude plugin marketplace add raychao-oao/pty-mcp
claude plugin install pty-mcp@pty-mcp

重启 Claude Code——会话启动时会自动下载二进制文件，然后再重启一次以启用它。无需手动执行 claude mcp add。

更新：

claude plugin marketplace update pty-mcp
claude plugin update pty-mcp@pty-mcp

重启 Claude Code——会话启动时会自动下载新版二进制文件，然后再重启一次以应用更新。

手动安装

一行命令完成安装并注册（macOS / Linux / WSL2）：

curl -fsSL https://raw.githubusercontent.com/raychao-oao/pty-mcp/main/install.sh | sh
claude mcp add pty-mcp -- /usr/local/bin/pty-mcp

重启 Claude Code 后即可使用这些工具。

chmod +x pty-mcp-*
sudo mv pty-mcp-* /usr/local/bin/pty-mcp
claude mcp add pty-mcp -- /usr/local/bin/pty-mcp

go install github.com/raychao-oao/pty-mcp@latest
claude mcp add pty-mcp -- $(go env GOPATH)/bin/pty-mcp

WSL2 说明

pty-mcp 在 WSL2 中开箱即用。请使用 Linux 二进制文件：

# Inside WSL2
curl -fsSL https://raw.githubusercontent.com/raychao-oao/pty-mcp/main/install.sh | sh
claude mcp add pty-mcp -- /usr/local/bin/pty-mcp

可选：在远程服务器上安装 ai-tmux

如需在 SSH 断开后仍保留持久会话，请在远程服务器上安装 ai-tmux：

# Download for your server's architecture
curl -fsSL https://raw.githubusercontent.com/raychao-oao/pty-mcp/main/install.sh | sh
# Or just copy the binary:
scp /usr/local/bin/ai-tmux your-server:/usr/local/bin/ai-tmux

使用示例

注册后，AI Agent 可以使用这些 MCP 工具：

本地交互式 shell：

create_local_session()                    → {session_id, type: "local"}
send_input(session_id, "cd /tmp && ls")   → {output: "...", is_complete: true}
send_input(session_id, "python3")         → start Python REPL
send_input(session_id, "print('hello')")  → {output: "hello\n>>>"}
send_control(session_id, "ctrl+d")        → exit Python
close_session(session_id)

通过 SSH 连接到远程服务：

create_ssh_session(host: "myserver", user: "admin")
send_input(session_id, "top")
send_control(session_id, "ctrl+c")        → stop top

等待匹配模式（v0.2.0）：

create_local_session("ping myserver")
read_output(session_id, wait_for: "bytes from", timeout: 300)
→ blocks until server responds or 5 min timeout

send_input(session_id, "docker-compose up")
read_output(session_id, wait_for: "ready|error", timeout: 60, context_lines: 3)
→ returns matched line + 3 lines of context

发送机密信息／密码（v0.3.0）：

# AI detects a password prompt, calls send_secret instead of handling the password itself
create_ssh_session(host: "router", user: "admin")
read_output(session_id, wait_for: "Password:")   → session is waiting for input

send_secret(session_id, prompt: "Router admin password:")
→ native GUI dialog appears on the operator's screen (macOS: system dialog,
   WSL2: Windows Get-Credential, Linux: zenity/kdialog)
→ operator types password — it is sent directly to the PTY session
→ AI only sees: {success: true, length: 12}
→ password never appears in AI context or logs

持久会话（SSH 断开后仍会保留）：

create_ssh_session(host: "server", user: "admin", persistent: true)
send_input(session_id, "make build")      → start long build
detach_session(session_id)                → disconnect, build continues

# Later (even after restart):
list_remote_sessions(host: "server", user: "admin")  → see running sessions
create_ssh_session(host: "server", user: "admin", session_id: "abc123")  → reattach
send_input(session_id, "echo $?")         → check build result

MCP 工具

¹ 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 窗口的进程，会导致宿主终端冻结（无法响应输入、滚动和选择），直到操作员关闭该终端，而且除此之外别无恢复办法。对话框只会一直等待，直到操作员作出答复或自行点击 Cancel，此时会正常退出。

审计日志

pty-mcp 提供可选的审计日志功能，可将每条 send_input 命令记录到中央收集器中。这让团队能够审查并追踪 AI Agent 在会话期间执行的操作。

重要提示： 这是一种自愿启用、自行报告的操作日志。它依赖操作员主动选择启用并运行收集器。由于 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-----

设置

每位操作员运行一次，以创建配置并生成令牌：

pty-mcp audit init

这会创建 ~/.config/pty-mcp/config（chmod 600），其中包含随机生成的令牌，并打印该令牌，供你分享给采集器管理员。

采集器管理员启动服务（使用 init 输出中的令牌）：

PTY_MCP_AUDIT_TOKEN=<token-from-init> \
  pty-mcp audit serve --port 9099 --log /var/log/pty-mcp-audit.jsonl

在配置中设置采集器 URL 后，启用审计：

# Edit config and set: audit-url=http://your-collector:9099
pty-mcp audit enable
# Restart Claude Code to apply

如需暂时停止记录但保留配置：

pty-mcp audit disable

没有配置文件的操作员不受影响——审计默认关闭。

审计模式

查看日志

日志以 JSONL 格式存储（每行一个 JSON 对象），可使用标准工具读取：

# All commands by operator ray
grep '"user":"ray"' /var/log/pty-mcp-audit.jsonl | jq .

# Commands sent to a specific host
jq 'select(.target == "root@prod01")' /var/log/pty-mcp-audit.jsonl

ai-tmux：持久终端守护进程

ai-tmux 是一个轻量级守护进程，运行在远程服务上，可在 SSH 断开连接后保持 PTY 会话运行。可以把它看作是为 AI Agent 设计的 tmux。

在远程服务上安装

# Cross-compile for Linux
GOOS=linux GOARCH=amd64 go build -o ai-tmux-linux ./cmd/ai-tmux/

# Copy to server
scp ai-tmux-linux server:~/ai-tmux
ssh server "chmod +x ~/ai-tmux && sudo mv ~/ai-tmux /usr/local/bin/ai-tmux"

工作原理

• ai-tmux server — 守护进程模式，通过 Unix 套接字监听并管理 PTY 会话
• ai-tmux client — 桥接模式，通过标准输入/输出转发 JSON 协议（pty-mcp 通过 SSH 使用）
• ai-tmux list — 列出活动会话

当 pty-mcp 使用 persistent: true 连接时，守护进程会自动启动。会话在闲置 30 分钟后会被清理。

pty-mcp 会在打开会话前检查远程主机上的 ai-tmux --version，如果缺少该二进制文件或版本低于最低要求，则会返回明确错误，而不是晦涩的连接错误。

SSH 配置支持

pty-mcp 会读取 ~/.ssh/config 以解析主机别名：

# ~/.ssh/config
Host myserver
    HostName 192.168.1.100
    User admin
    Port 2222
    IdentityFile ~/.ssh/id_ed25519

create_ssh_session(host: "myserver", user: "admin")
# Automatically resolves hostname, port, and identity file

要求

• Go 1.25+
• 对于串行连接：适当的设备权限
• 对于持久会话：远程服务上的 ai-tmux 二进制文件

更新日志

版本历史请参阅 CHANGELOG.md。

许可证

MIT