mcp-interactive-terminal

Manages persistent, interactive terminal sessions for AI agents through xterm-headless, a headless terminal emulator that captures ANSI escape sequences and renders clean output. Sessions maintain state across multiple tool calls, enabling multi-step workflows like database queries, SSH connections, and REPL interactions without losing context or requiring session re-initialization.

Automatically detects when terminal output is complete and ready for the next command by analyzing ANSI escape sequences, prompt patterns, and output stability heuristics. Uses pattern matching on shell prompts (bash $, zsh %, etc.) and timeout-based detection to distinguish between incomplete output and command completion, preventing premature response cutoff.

Provides interactive database CLI environments (psql for PostgreSQL, mysql for MySQL, mongo for MongoDB) where Claude can execute queries, see results, and iterate based on output. Manages database connections, transaction state, and result formatting across multiple query invocations.

Provides interactive Python REPL environment where Claude can execute Python code, see results, and iterate based on output. Manages Python process state, variable scope, imported modules, and output capture across multiple code invocations, enabling exploratory programming and data analysis workflows.

Provides interactive Node.js REPL environment where Claude can execute JavaScript code, see results, and iterate based on output. Manages Node.js process state, variable scope, required modules, and output capture across multiple code invocations, enabling exploratory programming and testing workflows.

Supports execution across diverse interactive CLI environments including SSH sessions, Docker containers, database CLIs (psql, mysql, mongo), REPLs (Python, Node.js, Ruby), and custom interactive programs. Routes commands to the appropriate environment handler and maintains protocol-specific state (connection context, authentication, transaction state) across multiple invocations.

Implements multi-layer security controls including command allowlisting/denylisting, environment variable sandboxing, file system access restrictions, process isolation via containerization, network access controls, resource limits (CPU, memory, timeout), and audit logging. Each layer can be independently configured and enforced, preventing unauthorized system access while allowing legitimate interactive workflows.

Exposes terminal capabilities as MCP tools with standardized schemas, enabling Claude, Cursor, and Windsurf to discover and invoke terminal operations through the Model Context Protocol. Implements tool registration, parameter validation, response formatting, and error handling according to MCP specification, allowing AI agents to treat terminal operations as first-class tools.

Parses and renders ANSI escape sequences (colors, formatting, cursor positioning) from terminal output using xterm-headless emulation, preserving visual formatting information that would be lost in plain text capture. Converts raw terminal output into human-readable formatted text while maintaining semantic information about colors, bold, underline, and other formatting directives.

Maintains execution context across multiple command invocations including current working directory, environment variables, shell history, and session state. Each terminal session preserves state between calls, enabling workflows where later commands depend on earlier results (e.g., cd to directory, then run commands in that directory) without explicit state passing.

Captures and reports detailed error information including exit codes, stderr output, timeout conditions, and connection failures. Provides structured error responses that enable AI agents to understand failure modes and attempt recovery strategies (retry with different parameters, fallback commands, error diagnosis).

Provides isolated Docker container execution environments where terminal commands run inside containers rather than on the host system. Manages container lifecycle (creation, execution, cleanup) and enables running commands in specific container images with configurable resource limits, volume mounts, and environment variables.

Manages SSH connections to remote systems with persistent session state, enabling multi-step remote command execution without re-authentication. Handles SSH key authentication, password-based auth (with timeout handling), connection pooling, and automatic reconnection on transient failures.