Terminal Sessions MCP

Interactive, persistent terminal sessions for AI assistants via Model Context Protocol

Why This Matters

While many AI tools offer basic command execution, Terminal Sessions MCP provides unique capabilities:

What makes this different:

• Sessions survive IDE restarts - Unlike typical tools, your sessions persist even when you close Cursor/Claude Desktop
• Background tasks with log access - Run dev servers, builds, or tests in background while retaining full access to their output
• True interactivity - Send input to prompts, handle confirmations, respond to interactive tools
• Process control - Send signals (Ctrl+C, Ctrl+Z) to gracefully manage long-running processes
• Stateful environment - cd, export, and environment changes persist across commands
• Visual debugging - Take screenshots of terminal output to debug TUI applications
• Context search - Search through command history and output with regex

Your AI assistant can now run servers in the background while working on other tasks, maintain persistent development environments, handle interactive workflows, and even build terminal UI applications with visual feedback.

MCP Features

✅ Truly Persistent Sessions - Sessions survive Cursor/IDE restarts, keeping all state
✅ Interactive Workflows - Handle password prompts, confirmations, and interactive tools
✅ Build & Debug TUIs - Develop terminal UI apps with visual feedback via screenshots
✅ Process Control - Send signals (SIGINT, SIGTERM, SIGTSTP) to running processes
✅ Stateful Shell - cd, export, and other state changes persist across AI responses
✅ Log Search - Search through command history and output with regex and context
✅ Service Management - Start services with intelligent readiness detection
✅ Smart Command Execution - Detects when commands complete, handles long-running processes
✅ Multi-Session Management - Track multiple services/sessions by name
✅ Terminal Screenshots - Capture visually rich terminal output for debugging
✅ Real-Time Streaming - Watch output as it happens, not just final results

Quick Start for AI Assistants

1. Install

Option A: Global install (recommended)

npm install -g term-sessions-mcp

Option B: Local install

npm install term-sessions-mcp

2. Start the Terminal Session Server

This is the backend server that actually manages your terminal sessions:

If installed globally:

session-server
# Starts session server on port 3100 (with GUI on port 3200)

If installed locally:

npx session-server

Headless mode (no GUI):

session-server --headless

Remote access (bind to all interfaces):

session-server --host 0.0.0.0 --token your-secret-token

Who may connect. Both ports (the session API and the web GUI) refuse