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