Persistent Terminal

You can run and manage persistent, long-running terminal sessions from an MCP server. It keeps commands running across disconnects, supports multiple sessions, and provides a visual web UI and REST endpoints for easy control and monitoring. This makes it ideal for AI assistants and automated workflows that rely on durable terminal interactions.

How to use

You connect to the MCP server using client tools that implement the MCP protocol. Start a persistent terminal session, write commands to it, and read the buffered output. Use the web UI for interactive command entry and live terminal rendering, or use REST endpoints to manage terminals programmatically. The server supports multiple independent terminals, incremental reads, and intelligent output handling to keep noise low while preserving important logs.

How to install

# Quick start with npx (recommended)
npx persistent-terminal-mcp

# REST API server (optional)
npx persistent-terminal-mcp-rest

If you prefer to install as a package for local development, you can install the core package and then import the classes in your code.

npm install persistent-terminal-mcp

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

Configuration and usage notes

The server provides configurable environment variables to tailor behavior, including buffer size, session timeout, animation compression, and REST/UI auto-start options.

# Common environment variables
MAX_BUFFER_SIZE=10000
SESSION_TIMEOUT=86400000
COMPACT_ANIMATIONS=true
ANIMATION_THROTTLE_MS=100

# REST/UI auto-start options
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

Web UI overview

Open a browser to interact with the real-time terminal. The Web UI renders terminals with proper ANSI colors using a WebSocket connection, supports sending commands, and automatically manages multiple terminal instances.

# Start the web UI (if not started automatically)
npx persistent-terminal-mcp
# Then navigate to the UI URL displayed in the startup output

Client configuration examples

To connect Claude Desktop or Claude Code, configure MCP servers in the client with the recommended command to launch the MCP server locally. The examples below show how to reference the MCP binary via npx.

# Claude Desktop / Claude Code (example)
{
  "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"
      }
    }
  }
}

REST API endpoints overview

If you enable the REST version, you can manage terminals through HTTP endpoints. You can create terminals, list them, write input, and read outputs via the exposed API.

Troubleshooting and tips

• Use wait_for_output to ensure you collect complete command output before reading results. - The spinner animations can be compressed to reduce noise while preserving logs. - The system supports interactive applications like vim and npm create, with proper ANSI handling.

Security and stability

The server is designed to be robust: it auto-reconnects on disruption, cleans up idle sessions, and handles ANSI escape sequences correctly. Logs go to stderr to avoid polluting MCP communication channels.

Examples and quick-start scripts

npm run example:basic        # Create → Write → Read → Terminate
npm run example:smart        # Smart read modes: head, tail, head-tail
npm run example:spinner      # Spinner compression demo
npm run example:webui        # Web UI demo
npm run test:tools           # Run all MCP tools
npm run test:fixes           # Run fix-related tests

API and tools overview

You will find a set of endpoints and functions to manage terminals and read outputs. Functions include creating terminals, writing input, reading outputs in different modes, waiting for stable output, and opening the UI.

Available tools

create_terminal

Create a new persistent terminal session with optional working directory, environment, and size.

create_terminal_basic

Create a simplified terminal session with essential options.

write_terminal

Send input to a running terminal, with optional newline handling.

read_terminal

Read terminal output with modes like full, head, tail, or head-tail.

wait_for_output

Wait for terminal output to stabilize before reading.

get_terminal_stats

Retrieve statistics about a specific terminal.

list_terminals

List all active terminals.

kill_terminal

Terminate a running terminal with a signal.

open_terminal_ui

Launch the Web-based terminal management interface.

fix_bug_with_codex

Automatically analyze and fix code bugs using Codex CLI and generate a report.