持久终端-mcp

Name: 持久终端-mcp
Author: masx200

作者：masx2002 星标更新：2025-11-19

安装使用来源：spider==github.com

项目介绍

持久终端 MCP 服务器

英文

一个强大的模型上下文协议（MCP）服务器，基于 TypeScript 和 node-pty 实现持久终端会话管理。即使客户端断开连接，终端命令也会继续运行，特别适合像 Claude、Cursor 和 Cline 这样的 AI 助手执行长时间运行的任务。 YouTube 视频链接: https://youtu.be/nfLi1IZxhJs Bilibili 视频链接: https://www.bilibili.com/video/BV14ksPzqEbM/

Windows 配置 MCP 视频教程链接: https://youtu.be/WYEKwTQCAnc

✨ 核心特性

持久终端会话

长期运行 创建、重用和管理长时间运行的 shell 会话
断开后恢复传输 客户端断开后，终端继续运行，重新连接后可以恢复操作
多会话管理 同时管理多个独立的终端会话
自动清理 自动清理空闲会话以防止资源泄漏

🧠 智能输出管理

循环缓冲区 可配置大小（默认 10,000 行），自动管理内存
多种读取模式：
- full 完整输出
- head 仅读取前 N 行
- tail 仅读取最后 N 行
- head-tail 同时从开头和结尾读取
增量读取 使用 since 参数仅读取新添加的内容
令牌估计 自动估算输出令牌的数量，便于 AI 控制上下文

🎨 Spinner 动画压缩

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

🌐 基于 Web 的可视化管理界面

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

🤖 Codex 自动修复错误

完全自动化 集成 OpenAI Codex CLI 自动修复代码错误
文档驱动 将 AI 描述保存为 MD 文档，Codex 读取并修复
详细报告 生成完整的修复报告，包括修改前后的对比
智能等待 自动检测 Codex 执行完成，默认超时时间为 1_分钟
历史记录 所有错误描述和修复报告永久保存在 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",
      "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" 并移除中间的 -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": "1_00"
      }
    }
  }
}

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 格式)
# 用于配置 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 格式)
# 用于配置 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`	启动时自动启动 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 服务器：

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

客户端配置示例

将环境变量添加到 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

🧱 TypeScript 程序化使用

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 工具概述

工具	功能	主要参数
`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`	列出所有活跃终端	None
`kill_terminal`	终止会话	`terminalId`, `signal`
`open_terminal_ui` 打开 Web 管理界面 `port`, `autoOpen`
`fix_bug_with_codex` 🆕	使用 Codex 自动修复错误	`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（可选）：头部模式下的行数，默认 50
tailLines（可选）：尾部模式下的行数，默认 50
stripSpinner（可选）：是否压缩 Spinner 动画

output 输出内容
totalLines

持久终端-mcp

项目介绍

持久终端 MCP 服务器

✨ 核心特性

持久终端会话

🧠 智能输出管理

🎨 Spinner 动画压缩

🌐 基于 Web 的可视化管理界面

🤖 Codex 自动修复错误

🔌 多种集成方法

🛡️ 稳定性保障

🚀 安装方法

✅ 快速运行（推荐）

📦 引入现有项目

🌐 全局安装（可选）

🧪 本地开发

🐞 调试模式

📚 示例脚本

⚙️ MCP 客户端配置

Claude Desktop

macOS / Linux

Windows

Claude Code

macOS / Linux

Windows

⚠️ Windows 用户请注意

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

🚫 不建议使用命令行方法

📖 在 Windows 上配置 persistent-terminal MCP

Cursor / Cline

Codex

macOS / Linux

Windows

环境变量描述

🚀 自动服务器启动配置

外部访问配置

使用效果

客户端配置示例

🧱 TypeScript 程序化使用

🛠️ MCP 工具概述

详细工具描述

create_terminal - 创建终端

write_terminal - 写入命令

read_terminal - 读取输出

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

`create_terminal` - 创建终端

`write_terminal` - 写入命令

`read_terminal` - 读取输出