Terminal Control MCP Server

A modern MCP server that enables AI agents to control terminal sessions through persistent tmux-based sessions. Features real-time web interface for direct user access, comprehensive security controls, and support for interactive terminal programs including debuggers, SSH connections, and database clients.

✨ Features

🖥️ Tmux-Based Terminal Control

• Reliable Backend: Built on tmux and libtmux for stable terminal multiplexing
• Session Persistence: Long-running sessions with automatic cleanup and monitoring
• Raw Stream Capture: Direct terminal output via tmux pipe-pane
• Agent-Controlled: AI agents manage timing and interaction flow without automatic timeouts
• Flexible Content Modes: Get screen, history, since-input, or tail output for optimal workflow control
• Dual Access: Both agent (MCP tools) and user (web browser) can interact simultaneously

🌐 Optional Web Interface

• Real-time Terminal: Live xterm.js terminal emulator with WebSocket updates
• Session URLs: Direct browser access to any terminal session
• Zero Setup: Automatic web server startup with configurable networking
• Manual Control: Send commands directly without interrupting agent workflows
• Session Management: View all active sessions and their status

🛡️ Comprehensive Security

• Command Filtering: Block dangerous operations (rm -rf /, sudo, disk formatting, etc.)
• Path Protection: Restrict access to user directories only
• Rate Limiting: 60 calls/minute with session limits (max 50 concurrent)
• History Isolation: Prevent terminal sessions from polluting system history
• Audit Logging: Complete security event tracking
• Input Validation: Multi-layer validation for all inputs
• Configurable Levels: Off, low, medium, high protection levels

🚀 Quick Start

System Requirements

This package requires tmux for terminal multiplexing:

# Ubuntu/Debian
sudo apt update && sudo apt install -y tmux

# macOS
brew install tmux

# CentOS/RHEL/Fedora
sudo yum install tmux  # or sudo dnf install tmux

Python Requirements: Python 3.9 or later

Installation

From PyPI (Recommended)

# Install directly from PyPI
pip install terminal-control-mcp

From Source

# Clone the repository
git clone https://github.com/wehnsdaefflae/terminal-control-mcp.git
cd terminal-control-mcp

# Create virtual environment (choose one)
python -m venv .venv          # Using standard venv
# OR
uv venv                       # Using uv (faster)

# Activate virtual environment
source .venv/bin/activate     # Linux/macOS
# .venv\Scripts\activate      # Windows

# Install the package
pip install .

# Or install in development mode
pip install -e ".[dev]"

Configuration

The server supports configuration through TOML files and environment variables:

Claude Code (Anthropic)

# Add the MCP server