Persistent Terminal MCP

🚀 持久化终端 MCP 服务器

这是一个功能强大的 Model Context Protocol (MCP) 服务器，基于 TypeScript 和 node-pty 实现持久化终端会话管理。即便客户端断开连接，终端命令仍会继续运行，尤其适用于 Claude、Cursor、Cline 等 AI 助手执行长时间任务。

• 油管视频地址：https://youtu.be/nfLi1IZxhJs
• b站视频地址：https://www.bilibili.com/video/BV14ksPzqEbM/
• Windows 配置 mcp 视频教程地址：https://youtu.be/WYEKwTQCAnc

🚀 快速开始

本项目是一个强大的 MCP 服务器，能实现持久化终端会话管理。你可以通过以下方式快速体验：

• 若想直接使用，可通过 npx 启动：

npx persistent-terminal-mcp

• 若需 REST 版本，使用以下命令：

npx persistent-terminal-mcp-rest

✨ 主要特性

🔥 持久化终端会话

• 长期运行：可创建、复用和管理长期运行的 Shell 会话。
• 断线续传：客户端断开连接后，终端命令继续运行，重连后可继续操作。
• 多会话管理：能同时管理多个独立的终端会话。
• 自动清理：超时会话自动清理，避免资源泄漏。

🧠 智能输出管理

• 循环缓冲区：可配置大小（默认 10,000 行），自动管理内存。
• 多种读取模式：
  • full：完整输出。
  • head：只读取开头 N 行。
  • tail：只读取末尾 N 行。
  • head-tail：同时读取开头和末尾。
• 增量读取：使用 since 参数只读取新增内容。
• Token 估算：自动估算输出的 token 数量，方便 AI 控制上下文。

🎨 Spinner 动画压缩

• 自动检测：识别常见的进度动画字符（如 ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏, ◐◓◑◒ 等）。
• 智能节流：减少 npm install、yarn、pnpm 等命令的噪音输出。
• 保留关键信息：压缩动画的同时保留真实日志。
• 灵活配置：可通过环境变量或参数控制开关。

🌐 Web 可视化管理界面

• 实时终端：基于 xterm.js 的终端渲染，支持完整 ANSI 颜色。
• WebSocket 推送：终端输出实时显示，无需刷新。
• 交互操作：可直接在浏览器中发送命令、查看输出。
• 多实例支持：自动端口分配，支持多个 AI 客户端同时使用。
• VS Code 风格：暗色主题，简洁美观的界面设计。

🤖 Codex 自动修复 Bug

• 完全自动化：集成 OpenAI Codex CLI，自动修复代码 Bug。
• 文档驱动：AI 描述保存为 MD 文档，Codex 读取并修复。
• 详细报告：生成完整的修复报告，包含修改前后对比。
• 智能等待：自动检测 Codex 执行完成，默认超时 10 分钟。
• 历史记录：所有 Bug 描述和修复报告永久保存在 docs/ 目录。

🔌 多种集成方式

• MCP 协议：原生支持 Claude Desktop、Claude Code、Cursor、Cline 等客户端。
• REST API：提供 HTTP 接口，方便非 MCP 场景集成。
• 严格兼容：完全符合 MCP stdio 协议规范，stdout 纯净无污染。

🛡️ 稳定性保障

• 输出稳定检测：wait_for_output 工具确保获取完整输出。
• 交互式应用支持：完美支持 vim、npm create 等交互式程序。
• ANSI 转义序列：正确处理终端控制字符。
• 错误恢复：自动重连、异常处理机制。

📦 安装指南

✅ 快速运行（推荐）

无需安装，直接使用 npx 启动：

npx persistent-terminal-mcp

REST 版本同样支持：

npx persistent-terminal-mcp-rest

📦 引入到现有项目

npm install persistent-terminal-mcp

安装后即可在代码中引用所有核心类与类型：

import { PersistentTerminalMcpServer } from "persistent-terminal-mcp";

🌐 全局安装（可选）

npm install --global persistent-terminal-mcp
persistent-terminal-mcp

💻 使用示例

基础用法

import {
  PersistentTerminalMcpServer,
  TerminalManager,
  RestApiServer,
} from "persistent-terminal-mcp";

const manager = new TerminalManager();
const rest = new RestApiServer(manager);
await rest.start(3001);

const mcpServer = new PersistentTerminalMcpServer();
const server = mcpServer.getServer();
await server.connect(/* 自定义 transport */);

所有核心类和类型在包的根入口即可获取，详情可参考 src/index.ts。

📚 详细文档

MCP 客户端配置

Claude Desktop

• macOS / Linux：
  • 配置文件位置：~/Library/Application Support/Claude/claude_desktop_config.json
  • 在配置文件中添加以下内容：

{
  "mcpServers": {
    "persistent-terminal": {
      "command": "npx",
      "args": ["-y", "persistent-terminal-mcp"],
      "env": {
        "MAX_BUFFER_SIZE": "10000",
        "SESSION_TIMEOUT": "86400000",
        "COMPACT_ANIMATIONS": "true",
        "ANIMATION_THROTTLE_MS": "100"
      }
    }
  }
}

• 说明：
  • -y 参数会自动确认 npx 的下载提示。
  • 若已全局安装（npm install -g persistent-terminal-mcp），可将 command 改为 "persistent-terminal-mcp" 并移除 args 中的 -y。
• Windows：
  • 配置文件位置：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "persistent-terminal": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "persistent-terminal-mcp"],
      "env": {
        "MAX_BUFFER_SIZE": "10000",
        "SESSION_TIMEOUT": "86400000",
        "COMPACT_ANIMATIONS": "true",
        "ANIMATION_THROTTLE_MS": "100"
      }
    }
  }
}

• 说明：
  • Windows 需要通过 cmd /c 来调用 npx。
  • 若已全局安装，可将 args 改为 ["/c", "persistent-terminal-mcp"]。

Claude Code

• macOS / Linux：
  • 使用命令行快速添加：

claude mcp add persistent-terminal \
  --env MAX_BUFFER_SIZE=10000 \
  --env SESSION_TIMEOUT=86400000 \
  --env COMPACT_ANIMATIONS=true \
  --env ANIMATION_THROTTLE_MS=100 \
  -- npx -y persistent-terminal-mcp

• 或者编辑配置文件 ~/.claude.json：

{
  "mcpServers": {
    "persistent-terminal": {
      "command": "npx",
      "args": ["-y", "persistent-terminal-mcp"],
      "env": {
        "MAX_BUFFER_SIZE": "10000",
        "SESSION_TIMEOUT": "86400000",
        "COMPACT_ANIMATIONS": "true",
        "ANIMATION_THROTTLE_MS": "100"
      }
    }
  }
}

• Windows：

  ⚠️ Windows 用户请注意

  Claude Code 在 Windows 下 claude mcp add 命令存在参数解析问题

  🚫 不推荐使用命令行方式

  请参考专门的配置文档：

  📖 《Windows 下配置 persistent-terminal MCP》

  该文档提供了两种推荐方案：

  • ✅ 项目级配置（推荐）：在项目根目录创建 .mcp.json 文件
  • ✅ 全局配置：使用 Python 脚本修改 ~/.claude.json

Cursor / Cline

配置方式与 Claude Desktop 类似，请参考各客户端的 MCP 配置文档。

Codex

• macOS / Linux： 在 .codex/config.toml 文件中添加以下配置：

# MCP Server Configuration (TOML Format)
# 用于配置 persistent-terminal MCP 服务器

[mcp_servers.persistent-terminal]
command = "npx"
args = ["-y", "persistent-terminal-mcp"]

[mcp_servers.persistent-terminal.env]
MAX_BUFFER_SIZE = "10000"
SESSION_TIMEOUT = "86400000"
COMPACT_ANIMATIONS = "true"
ANIMATION_THROTTLE_MS = "100"

• Windows： 在 .codex/config.toml 文件中添加以下配置：

# MCP Server Configuration (TOML Format)
# 用于配置 persistent-terminal MCP 服务器

[mcp_servers.persistent-terminal]
command = "cmd"
args = ["/c", "npx", "-y", "persistent-terminal-mcp"]

[mcp_servers.persistent-terminal.env]
MAX_BUFFER_SIZE = "10000"
SESSION_TIMEOUT = "86400000"
COMPACT_ANIMATIONS = "true"
ANIMATION_THROTTLE_MS = "100"

说明：Windows 需要通过 cmd /c 来调用 npx。

环境变量说明

变量	说明	默认值
MAX_BUFFER_SIZE	缓冲区最大行数	10000
SESSION_TIMEOUT	会话超时时间（毫秒）	86400000 (24小时)
COMPACT_ANIMATIONS	是否启用 Spinner 压缩	true
ANIMATION_THROTTLE_MS	动画节流时间（毫秒）	100
MCP_DEBUG	是否启用调试日志	false
AUTO_START_REST_SERVER	MCP 启动时自动启动 REST 服务器	false
REST_HOST	REST 服务器监听地址	localhost
REST_PORT	REST 服务器端口	3001
AUTO_START_TERMINAL_UI	REST 启动时自动启动 Web UI	true
WEB_UI_HOST	Web UI 服务器监听地址	localhost
AUTO_OPEN_BROWSER	是否自动打开浏览器访问 Web UI	false
WEB_UI_PORT	Web UI 服务器端口	3000

🚀 自动启动服务器配置

通过环境变量可以实现服务器的自动启动和网络访问配置：

外部访问配置

要让 REST API 和 Web UI 支持外部网络访问，设置以下环境变量：

# 自动启动 REST API 服务器
AUTO_START_REST_SERVER=true

# REST API 监听所有网络接口（允许外部访问）
REST_HOST=0.0.0.0

# 自动启动 Web UI 界面
AUTO_START_TERMINAL_UI=true

# Web UI 监听所有网络接口（允许外部访问）
WEB_UI_HOST=0.0.0.0

# REST API 端口（可选）
REST_PORT=3001

# Web UI 端口（可选）
WEB_UI_PORT=3000

# 是否自动打开浏览器（可选）
AUTO_OPEN_BROWSER=false

使用效果

设置上述环境变量后，启动 MCP 服务器时会：

1. ✅ REST API 服务器自动启动在 http://0.0.0.0:3001
2. ✅ Web UI 自动启动在 http://0.0.0.0:3000
3. ✅ 两个服务都可以从外部网络访问
4. ✅ 可选择是否自动打开浏览器

客户端配置示例

将环境变量添加到 MCP 客户端配置中： Claude Desktop 配置：

{
  "mcpServers": {
    "persistent-terminal": {
      "command": "npx",
      "args": ["-y", "persistent-terminal-mcp"],
      "env": {
        "AUTO_START_REST_SERVER": "true",
        "REST_HOST": "0.0.0.0",
        "AUTO_START_TERMINAL_UI": "true",
        "WEB_UI_HOST": "0.0.0.0",
        "WEB_UI_PORT": "3000",
        "AUTO_OPEN_BROWSER": "false",
        "MAX_BUFFER_SIZE": "10000",
        "SESSION_TIMEOUT": "86400000"
      }
    }
  }
}

Claude Code 配置：

claude mcp add persistent-terminal \
  --env AUTO_START_REST_SERVER=true \
  --env REST_HOST=0.0.0.0 \
  --env AUTO_START_TERMINAL_UI=true \
  --env WEB_UI_HOST=0.0.0.0 \
  --env WEB_UI_PORT=3000 \
  --env AUTO_OPEN_BROWSER=false \
  -- npx -y persistent-terminal-mcp

Web 管理界面

功能特性

• 📊 终端列表：查看所有终端的状态、PID、Shell、工作目录等信息。
• 🖥️ 实时终端：使用 xterm.js 渲染终端输出，支持 ANSI 颜色。
• ⚡ 实时更新：WebSocket 推送，终端输出实时显示。
• ⌨️ 交互操作：直接在浏览器中发送命令。
• 🎨 VS Code 风格：暗色主题，简洁美观。
• 🔄 自动端口：支持多实例，自动避免端口冲突。

快速使用

在 Claude 或其他 MCP 客户端中说：

请打开终端管理界面

或者直接运行测试脚本：

npm run test:webui

详细使用说明见 Web UI 使用指南。

REST API（可选）

如果需要 HTTP 接口，可启动 REST 版本：

npx persistent-terminal-mcp-rest

服务器默认监听 3001 端口（可配置），端点与 MCP 工具一一对应：

端点	方法	说明
/api/terminals	POST	创建终端
/api/terminals	GET	列出所有终端
/api/terminals/:id	GET	获取终端详情
/api/terminals/:id	DELETE	终止终端
/api/terminals/:id/input	POST	发送命令
/api/terminals/:id/output	GET	读取输出
/api/terminals/:id/stats	GET	获取统计信息

项目结构

persistent-terminal-mcp/
├── src/                    # TypeScript 源码
│   ├── index.ts           # MCP 服务器入口
│   ├── mcp-server.ts      # MCP 服务器实现
│   ├── terminal-manager.ts # 终端管理器
│   ├── output-buffer.ts   # 输出缓冲区
│   ├── web-ui-manager.ts  # Web UI 管理器
│   ├── web-ui-server.ts   # Web UI 服务器
│   ├── rest-server.ts     # REST API 服务器
│   ├── types.ts           # 类型定义
│   ├── __tests__/         # 单元测试
│   └── examples/          # 示例脚本
├── dist/                   # 编译后的 JavaScript
├── public/                 # Web UI 静态文件
├── docs/                   # 文档
│   ├── guides/            # 使用指南
│   ├── reference/         # 技术参考
│   ├── clients/           # 客户端配置
│   └── zh/                # 中文文档
├── tests/                  # 测试套件
│   └── integration/       # 集成测试
└── scripts/                # 辅助脚本

文档导航

快速访问

• 📖 完整文档索引
• 🚨 修复文档索引
• 🧪 集成测试说明
• 🌐 Web UI 使用指南

按分类

• 使用指南：使用说明 | 故障排查 | MCP 配置
• 技术参考：技术细节 | 工具总结
• 修复文档：Stdio 修复 | Cursor 修复 | 终端修复
• 客户端配置：Claude Desktop/Code

🔧 技术细节

MCP 工具一览

工具	作用	主要参数
create_terminal	创建持久终端会话	shell, cwd, env, cols, rows
create_terminal_basic	精简版创建入口	shell, cwd
write_terminal	向终端写入命令	terminalId, input, appendNewline
read_terminal	读取缓冲输出	terminalId, mode, since, stripSpinner
wait_for_output	等待输出稳定	terminalId, timeout, stableTime
get_terminal_stats	查看统计信息	terminalId
list_terminals	列出所有活跃终端	无
kill_terminal	终止会话	terminalId, signal
open_terminal_ui	打开 Web 管理界面	port, autoOpen
fix_bug_with_codex 🆕	使用 Codex 自动修复 Bug	description, cwd, timeout

工具详细说明

create_terminal - 创建终端

创建一个新的持久化终端会话。 参数：

• shell (可选): Shell 类型，如 /bin/bash、/bin/zsh
• cwd (可选): 工作目录
• env (可选): 环境变量对象
• cols (可选): 终端列数，默认 80
• rows (可选): 终端行数，默认 24 返回：
• terminalId: 终端 ID
• status: 状态
• pid: 进程 ID
• shell: Shell 类型
• cwd: 工作目录

write_terminal - 写入命令

向终端发送命令或输入。 参数：

• terminalId: 终端 ID
• input: 要发送的内容
• appendNewline (可选): 是否自动添加换行符，默认 true 提示：默认会自动添加换行符执行命令，如需发送原始控制字符（如方向键），请设置 appendNewline: false。

read_terminal - 读取输出

读取终端的缓冲输出，支持多种智能截断模式。 参数：

• terminalId: 终端 ID
• mode (可选): 读取模式
  • full: 完整输出（默认）
  • head: 只读取开头
  • tail: 只读取末尾
  • head-tail: 同时读取开头和末尾
• since (可选): 从第 N 行开始读取（增量读取）
• maxLines (可选): 最大行数，默认 1000
• headLines (可选): head 模式的行数，默认 50
• tailLines (可选): tail 模式的行数，默认 50
• stripSpinner (可选): 是否压缩 Spinner 动画 返回：
• output: 输出内容
• totalLines: 总行数
• lineRange: 实际返回的行范围
• estimatedTokens: 估算的 token 数量
• truncated: 是否被截断
• spinnerCompacted: 是否进行了 Spinner 压缩

wait_for_output - 等待输出稳定

等待终端输出稳定后再读取，确保获取完整输出。 参数：

• terminalId: 终端 ID
• timeout (可选): 最大等待时间（毫秒），默认 5000
• stableTime (可选): 稳定时间（毫秒），默认 500 使用场景：
• 执行命令后确保获取完整输出
• 等待交互式应用启动完成

fix_bug_with_codex 🆕 - 自动修复 Bug

使用 OpenAI Codex CLI 自动分析和修复代码中的 Bug。 参数：

• description (必需): 详细的 Bug 描述，必须包含：
  • 问题症状（具体的错误行为）
  • 期望行为（应该如何工作）
  • 问题位置（文件路径、行号、函数名）
  • 相关代码（有问题的代码片段）
  • 根本原因（为什么会出现这个问题）
  • 修复建议（如何修复）
  • 影响范围（还会影响什么）
  • 相关文件（所有相关的文件路径）
  • 测试用例（如何验证修复是否有效）
  • 上下文信息（有助于理解问题的背景）
• cwd (可选): 工作目录，默认为当前目录
• timeout (可选): 超时时间（毫秒），默认 600000（10 分钟） 返回：
• terminalId: 执行 Codex 的终端 ID
• reportPath: 修复报告路径
• reportExists: 报告是否存在
• workingDir: 工作目录
• executionTime: 执行时间（秒）
• timedOut: 是否超时
• output: 终端输出
• reportPreview: 报告预览 工作流程：

1. AI 提供详细的 Bug 描述
2. 工具将描述保存到 docs/codex-bug-description-TIMESTAMP.md
3. Codex 读取文档并分析问题
4. Codex 修复 Bug 并生成报告 docs/codex-fix-TIMESTAMP.md
5. AI 读取报告并总结给用户 重要提示：

• ⚠️ 此工具具有完全系统访问权限（danger-full-access）
• ⚠️ Codex 可以修改任何文件，建议在 Git 仓库中使用
• ✅ 只使用英文描述（避免 UTF-8 编码问题）
• ✅ 描述越详细，修复质量越高 示例：

fix_bug_with_codex({
  description: `Username validation bug in auth.js file.

PROBLEM:
- File: src/auth/login.ts, line 45
- Code: const usernameRegex = /^[a-zA-Z0-9]{3,20}$/
- Symptom: Username 'user_name' is rejected with 'Invalid username' error
- Expected: Should accept usernames with underscores and hyphens

ROOT CAUSE:
- Regex [a-zA-Z0-9] only allows letters and numbers
- Missing support for underscore and hyphen characters

SUGGESTED FIX:
- Change regex to: /^[a-zA-Z0-9_-]{3,20}$/

VERIFICATION:
- Run: npm test
- Expected: all tests pass`,
  cwd: "/path/to/project",
  timeout