Skip to main content
Glama
deenesjakoruzh
raychao-oao

pty-mcp

by raychao-oao
OverviewSchemaRelated ServersScoreDiscussions
Go
Hybrid

pty-mcp

pty-mcp MCP server

一个 MCP (Model Context Protocol) 服务器，为 AI 智能体提供交互式终端会话 —— 包括本地 Shell、SSH、串口以及在断开连接后依然存活的远程持久化会话。

专为系统管理员和网络工程师打造，旨在让 AI 能够协助进行真实的服务器和设备管理，而不仅仅是代码生成。

AI 智能体通过 pty-mcp 与 Telehack BBS 交互

为什么需要它

AI 智能体通常在非交互式 Shell 中运行命令。它们无法：

  • SSH 登录服务器并与正在运行的进程交互

  • 通过串口控制台连接到路由器或交换机

  • 监控日志并在特定事件发生时做出反应

  • 在多个命令之间保持会话状态

  • 等待服务器重启并检测其何时恢复在线

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

如果没有 pty-mcp，AI 智能体只能求助于 sleep 30 && check_status 循环 —— 这会浪费 CPU 周期和 API 调用来等待事件发生。使用 wait_for，智能体会阻塞在服务器端，直到事件发生。减少轮询，降低能耗，对北极熊更友好。🐻❄️

使用场景

服务器管理

# 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

功能特性

功能

描述

本地终端

在本地机器上进行交互式 bash/python/node 会话

SSH 会话

通过密钥/密码认证连接远程主机，支持 SSH 配置

串口

通过串口连接设备（物联网、嵌入式、网络设备）

持久化会话

通过 ai-tmux 守护进程，会话在 SSH 断开后依然存活

挂载/分离

从运行中的会话分离，稍后重新连接

控制键

发送 ctrl+c, ctrl+d, 方向键, tab, escape

稳定检测

在返回前等待输出稳定（智能超时）

模式匹配

wait_for 会阻塞直到输出中出现正则表达式匹配 (v0.2.0)

内存限制

环形缓冲区防止长时间运行的会话导致 OOM (v0.2.0)

审计日志

可选的自愿操作日志 —— 将 send_input 命令记录到收集器以供审查和溯源 (v0.8.0)

架构

┌─────────────────────────────────────────────────────┐
│ 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，工具即可使用。

从 GitHub Releases 下载：

前往 Releases，下载对应平台的二进制文件，并赋予执行权限：

平台

二进制文件

macOS (Apple Silicon)

pty-mcp-darwin-arm64

macOS (Intel)

pty-mcp-darwin-amd64

Linux (x86_64) / WSL2

pty-mcp-linux-amd64

Linux (ARM64)

pty-mcp-linux-arm64

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

从源码构建 (需要 Go 1.25+):

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 智能体可以使用以下 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 工具

工具

描述

create_local_session

启动本地交互式终端 (bash, python3, node 等)

create_ssh_session

SSH 登录远程主机 (支持 SSH 配置别名)

create_serial_session

连接到串口设备

send_input

发送命令并等待输出稳定

read_output

读取输出，可选择等待模式 (wait_for, timeout, context_lines, tail_lines)

send_control

发送控制键 (ctrl+c, ctrl+d, 方向键, tab 等)

send_secret

通过 GUI 对话框提示人类操作员输入密钥；将其发送到 PTY 会话而不暴露给 AI 上下文或日志 ¹

list_sessions

列出所有活动会话

close_session

关闭会话 (终止远程 PTY)

detach_session

断开连接但保持远程 PTY 运行

list_remote_sessions

列出远程主机上的持久化会话

¹ send_secret 平台支持：macOS 使用原生密码对话框 (osascript)。WSL2 使用 powershell.exe Get-Credential (Windows GUI 对话框)。带有显示服务器的 Linux 使用 zenity 或 kdialog。无头 Linux 回退到 /dev/tty。

审计日志

pty-mcp 包含一个可选的审计日志功能，可将每条 send_input 命令记录到中央收集器。这使团队能够审查和追踪 AI 智能体在会话期间的操作。

重要提示： 这是一个自愿的、自报告的操作日志。它依赖于操作员选择启用它并运行收集器。由于 pty-mcp 运行在操作员自己的机器上，没有技术机制可以强制执行日志记录 —— 不合规的操作员可以简单地在未启用审计的情况下运行 pty-mcp。此功能为需要它的团队提供了可追溯性，但在需要审计合规性的环境中，它不能替代系统级审计工具（例如 auditd、syslog 转发、SSH 会话录制）。

记录内容

  • 时间戳、操作员身份、会话 ID、会话类型（本地/ssh/串口）、目标主机

  • 通过 send_input 发送的确切输入（包括 raw=true 输入，如菜单选择）

  • 每个命令后的输出片段（前 2 KB）

  • 将命令与其输出关联的 cmd_id

send_secret 永远不会被记录 —— 通过 GUI 对话框输入的密钥不会出现在审计日志中。

设置

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

pty-mcp audit init

这将创建 ~/.config/pty-mcp/config (权限 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

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

审计模式

模式

行为

best-effort (默认)

无论日志是否写入，命令都会执行；条目会在后台排队并重试

strict

如果无法交付审计条目，send_input 将被拒绝；在日志记录是团队政策要求时使用

查看日志

日志以 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 是一个轻量级守护进程，运行在远程服务器上，使 PTY 会话在 SSH 断开连接后依然存活。可以将其视为专为 AI 智能体设计的 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 — 桥接模式，通过 stdin/stdout 转发 JSON 协议（由 pty-mcp 通过 SSH 使用）

  • ai-tmux list — 列出活动会话

当 pty-mcp 以 persistent: true 连接时，守护进程会自动启动。会话在 30 分钟不活动后会被回收。

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

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
2dRelease cycle
16Releases (12mo)

Resources

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/raychao-oao/pty-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server