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
claude mcp add terminal-control -s user terminal-control-mcp

# Verify installation
claude mcp list

The MCP server will be automatically launched by Claude Code when needed.

Other MCP Clients

For other MCP clients, add to your configuration:

{
  "mcpServers": {
    "terminal-control": {
      "command": "terminal-control-mcp",
      "cwd": "/path/to/working/directory"
    }
  }
}

🔧 Configuration

The server uses TOML configuration files with optional environment variable overrides. Environment variables can override any TOML setting for deployment flexibility.

Configuration File Locations

The server looks for configuration files in this order:

1. ./terminal-control.toml (current working directory)
2. ~/.config/terminal-control.toml (user configuration directory)
3. /etc/terminal-control.toml (system-wide configuration)
4. Built-in defaults (if no config file found)

Configuration Sections

[web] - Web Interface Settings

[web]
enabled = false         # Enable web interface (default: false)
host = "0.0.0.0"       # Bind address (default: "0.0.0.0")
port = 8080            # Port number (default: 8080)
auto_port = true       # Automatic unique port selection (default: true)
external_host = ""     # External hostname for URLs (optional)

Web Interface Modes:

• Enabled: Real-time web interface with xterm.js terminal emulator
• Disabled: Automatically opens system terminal windows attached to tmux sessions

Auto Port Selection: When auto_port=true, ports are automatically selected in the 9000-9999 range using hash(working_dir + process_id) % 1000 + 9000 to avoid conflicts between multiple instances.

[security] - Security Settings

[security]
level = "high"              # Security level: off, low, medium, high
max_calls_per_minute = 60   # Rate limiting (calls per minute)
max_sessions = 50           # Maximum concurrent sessions

Security Levels:

• off: No validation (⚠️ USE WITH EXTREME CAUTION)
• low: Basic input validation only
• medium: Standard protection (blocks common dangerous commands)
• high: Full protection (comprehensive validation and filtering)

[session] - Session Management

[session]
default_shell = "bash"                      # Default shell for new sessions
timeout = 30                                # Session startup timeout (seconds)
isolate_history = true                      # Prevent sessions from polluting system history
history_file_prefix = "mcp_session_history" # Prefix for isolated history files

History Isolation Features:

• Automatic Isolation: Each session gets isolated history files in temporary directories
• Multi-Shell Support: Supports bash, zsh, fish, csh, tcsh, Python REPL, Node.js, PostgreSQL, MySQL
• Session-Specific Files: History files are prefixed with session IDs for complete isolation
• Automatic Cleanup: All history files are automatically deleted when sessions terminate
• Configurable: Can be disabled via isolate_history = false if system history is preferred

Supported Applications:

• Bash: HISTFILE, HISTCONTROL, HISTSIZE, HISTFILESIZE
• Zsh: HISTFILE, ZDOTDIR, SAVEHIST, HISTSIZE
• Fish: XDG_CONFIG_HOME, XDG_DATA_HOME
• Python: PYTHONSTARTUP with readline configuration
• Node.js: NODE_REPL_HISTORY
• PostgreSQL: PSQL_HISTORY
• MySQL: MYSQL_HISTFILE

[terminal] - Terminal Settings

[terminal]
width = 120                      # Terminal width (columns)
height = 30                      # Terminal height (rows)
close_timeout = 5.0              # Terminal close timeout (seconds)
process_check_timeout = 1.0      # Process health check timeout (seconds)
polling_interval = 0.05          # Output polling interval (seconds)
send_input_delay = 0.1           # Delay after sending input (seconds)

Terminal Emulator Support: The system automatically detects available terminal emulators in order of preference:

• GNOME/GTK: gnome-terminal
• KDE: konsole
• XFCE: xfce4-terminal
• Elementary OS: io.elementary.terminal
• Generic: x-terminal-emulator, xterm
• macOS: Terminal (via open -a Terminal)
• Modern terminals: alacritty, kitty, terminator

Custom Terminal Emulator Configuration:

[terminal]
# Custom terminal emulator preferences (ordered by preference)
emulators = [
    { name = "my-terminal", command = ["my-terminal", "--exec"] },
    { name = "gnome-terminal", command = ["gnome-terminal", "--"] },
    { name = "konsole", command = ["konsole", "-e"] },
]

[logging] - Logging Configuration

[logging]
level = "INFO"    # Log level: DEBUG, INFO, WARNING, ERROR

Complete Configuration Example

Create terminal-control.toml in your project root:

[web]
enabled = false         # Use terminal windows instead of web interface
host = "0.0.0.0"
port = 8080
auto_port = true        # Automatic unique port selection

[security]
level = "high"
max_calls_per_minute = 60
max_sessions = 50

[session]
default_shell = "bash"
timeout = 30

[terminal]
width = 120
height = 30
close_timeout = 5.0
process_check_timeout = 1.0
polling_interval = 0.05
send_input_delay = 0.1

[logging]
level = "INFO"

🛠️ MCP Tools (6 Tools)

The server provides 6 MCP tools for complete terminal session lifecycle management:

Session Management

list_terminal_sessions

List all active terminal sessions with status information.

Returns:

• Session IDs, commands, and states
• Creation timestamps and last activity
• Total session count (max 50)
• Web interface URLs (if enabled)

exit_terminal

Terminate and cleanup a terminal session.

Parameters:

• session_id: Session ID to destroy

Features:

• Bidirectional cleanup: Sessions destroyed when agents call exit_terminal OR when users type exit
• Automatic monitoring: Dead sessions detected and cleaned up every 5 seconds
• Terminal window management: Closes associated terminal windows when web interface is disabled

Content Retrieval

get_screen_content

Get terminal content with precise control over output format.

Parameters:

• session_id: Session to get content from
• content_mode: Content retrieval mode
  • "screen" (default): Current visible screen only
  • "since_input": Output since last input command
  • "history": Full terminal history
  • "tail": Last N lines (requires line_count)
• line_count: Number of lines for tail mode

Returns:

• Terminal content based on mode
• Process running status
• ISO timestamp for agent timing decisions

Input Control

send_input

Send input to terminal sessions.

Parameters:

• session_id: Target session
• input_text: Text to send (supports escape sequences)

Important: Newlines are NOT automatically added.

---