MMCPMarkets
SP

sanshao85/persistent-terminal-mcp

开发工具

本页由 AI 翻译，技术细节请以原文为准。 查看原文

130 stars 33 forks 质量 80 趋势 16MIT
Repository Install

sanshao85/persistent-terminal-mcp 是从 https://github.com/sanshao85/persistent-terminal-mcp. 导入的 MCP 服务器候选

概览

sanshao85/persistent-terminal-mcp 是从 https://github.com/sanshao85/persistent-terminal-mcp. 导入的 MCP 服务器候选

概述（AI 翻译）

英语

一个功能强大的 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

✨ 核心特性

🔥 持久化终端会话

  • 长期运行：创建、复用、管理长期运行的 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 分钟

本页由 AI 翻译，技术细节请以原文为准。

README

以下为原文 README 节选，完整内容请查看原文。

Persistent Terminal MCP Server

English

一个功能强大的 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

✨ 核心特性

🔥 持久化终端会话

  • 长期运行：创建、复用、管理长期运行的 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

🧪 本地开发

适合想要修改源码或深入调试的场景：

npm install          # 安装依赖
npm run build        # 编译 TypeScript → dist/
npm start            # 通过 stdio 启动 MCP 服务器

开发阶段也可直接运行 TypeScript 源码：

npm run dev          # MCP 服务器 (tsx)
npm run dev:rest     # REST 服务器 (tsx)

🐞 调试模式

启用调试日志（输出到 stderr，不会干扰 MCP 通信）：

MCP_DEBUG=true persistent-terminal-mcp

📚 示例脚本

npm run example:basic        # 基础操作：创建 → 写入 → 读取 → 终止
npm run example:smart        # 智能读取：head/tail/head-tail 模式演示
npm run example:spinner      # Spinner 压缩功能演示
npm run example:webui        # Web UI 功能演示
npm run test:tools           # 全量验证所有 MCP 工具
npm run test:fixes           # 关键修复的回归测试

⚙️ MCP 客户端配置

Claude Desktop

macOS / Linux

配置文件位置: ~/Library/Application Support/Claude/claude_desktop_config.json

在配置文件中添加以下内容：

{
  "mcpServers": {
    "persistent-terminal": {
      "command": "npx",
在 GitHub 查看完整 README

安装

npx -y persistent-terminal-mcp
新手？先看 mcpskill.org 教程 →

配置

{ "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" } } } }