Skip to main content
Glama

Interactive Automation MCP Server

by wehnsdaefflae
GitHub
Python
MIT License
1
  • Linux
  • Apple
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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)
  • 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

# 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)
[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 (5 Tools)

The server provides 5 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. For command execution, explicitly include \n (e.g., "ls\n", "python\n").

Features:

  • Raw input support with escape sequences
  • No automatic timeouts (agent-controlled timing)
  • Parallel user input possible via web interface

Session Creation

open_terminal

Create new terminal sessions.

Parameters:

  • shell: Shell to use (bash, zsh, fish, sh, etc.)
  • working_directory: Starting directory (optional)
  • environment: Environment variables (optional)

Returns:

  • Unique session ID
  • Initial screen content
  • Web interface URL (if enabled)
  • Process startup status

Features:

  • Universal shell support
  • Environment and directory control
  • Immediate screen content availability

📚 Usage Examples

Basic Commands

# Natural language requests to Claude: "Start a Python session and show me what's on screen" "List all my active terminal sessions" "What's currently showing in the terminal?" "Type 'print(2+2)' in the Python session" "Close that debugging session"

Interactive Programs

# Complex interactive workflows: "Start a Python REPL and help me debug this script" "SSH into the server and check disk space" "Connect to MySQL and show me the database tables" "Run the debugger and set breakpoints in the main function" "Start a docker container and explore the filesystem"

Debugging Workflow

Using the included examples/example_debug.py:

# 1. Start debugging session "Debug the file examples/example_debug.py and show me the code" # 2. Explore and set breakpoints "Show me the source code around the current line" "Set a breakpoint where the bug occurs" # 3. Investigate the problem "Step through the buggy loop and show variable values" "What variables do we have here? Show their values" # 4. Clean up "We found the bug! Clean up this debugging session"

Pro tip: If you set web_enabled=true in your configuration, you can also access the debugging session directly in your browser for real-time interaction.

Web Interface Usage

When web interface is enabled:

  1. Agent creates session: "Starting debugger session..."
  2. Agent provides URL: "You can also access it at http://localhost:9123/session/abc123"
  3. User opens URL in browser for direct interaction
  4. Both agent and user can send commands simultaneously

🌐 Web Interface

Real-Time Terminal Access

  • Live output: See exactly what agents see in real-time
  • Manual input: Send commands directly without agent awareness
  • WebSocket updates: Automatic screen refreshes
  • Session overview: View all active sessions at once

Session URLs

  • Individual sessions: http://localhost:8080/session/{session_id}
  • Session overview: http://localhost:8080/
  • Direct browser access: No additional software required
  • Transparent to agents: Manual interaction doesn't interfere with agent control

🔒 Security

Defense-in-Depth Approach

  • Command filtering: Blocks dangerous operations (rm -rf /, sudo, dd, etc.)
  • Path restrictions: Commands run in specified directories only
  • Input validation: Multi-layer validation for all inputs
  • Environment protection: Protects critical variables (PATH, LD_PRELOAD, etc.)
  • Rate limiting: Prevents abuse with configurable limits
  • Audit logging: Complete security event tracking

Agent-Controlled Philosophy

  • Maximum flexibility: Security balanced with functionality
  • User responsibility: Security managed by user and agent choices
  • Transparent operation: All commands create persistent sessions
  • No hidden automation: Agents control all timing and interaction

📁 Project Structure

terminal-control-mcp/ ├── src/terminal_control_mcp/ │ ├── main.py # FastMCP server with 5 MCP tools │ ├── session_manager.py # Session lifecycle management │ ├── interactive_session.py # Tmux/libtmux process control │ ├── terminal_utils.py # Terminal window management │ ├── web_server.py # FastAPI web interface │ ├── security.py # Multi-layer security validation │ ├── config.py # TOML configuration handling │ ├── models.py # Pydantic request/response models │ ├── templates/ # Web interface templates │ │ ├── index.html # Session overview page │ │ └── session.html # Individual session interface │ └── static/ # Web interface assets │ ├── css/ # Stylesheets │ └── js/ # JavaScript modules ├── tests/ # Comprehensive test suite │ ├── test_security_manager.py │ ├── test_execute_command.py │ ├── test_session_lifecycle.py │ └── test_mcp_integration.py ├── examples/ │ └── example_debug.py # Sample debugging script ├── logs/interactions/ # Session interaction logs ├── CLAUDE.md # Development guidance ├── terminal-control.toml # TOML configuration └── pyproject.toml # Python packaging configuration

🧪 Development

Testing

# Run all tests pytest tests/ # Run specific test categories pytest -m unit # Unit tests pytest -m integration # Integration tests pytest -m security # Security tests # Run with coverage pytest --cov=src/terminal_control_mcp tests/

Code Quality

# Type checking mypy src/ --ignore-missing-imports # Linting and formatting ruff check src/ tests/ black src/ tests/ # Check for dead code vulture src/

Development Installation

# Install with development dependencies pip install -e ".[dev]" # Test basic functionality python tests/conftest.py

🚀 Development Status

  • ✅ Tmux Integration: Complete libtmux-based terminal control
  • ✅ Web Interface: Real-time xterm.js with WebSocket synchronization
  • ✅ Agent Control: 5 MCP tools for complete session management
  • ✅ Security Layer: Multi-layer validation and audit logging
  • ✅ TOML Configuration: Structured configuration with environment overrides
  • ✅ Type Safety: Full Pydantic models and mypy coverage
  • ✅ Test Coverage: Comprehensive test suite with multiple categories
  • ✅ Production Ready: Reliable session management with proper cleanup

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes and add tests
  4. Ensure all tests pass:
    ruff check src/ tests/ && mypy src/ --ignore-missing-imports && pytest tests/
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

🙏 Acknowledgments

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

A comprehensive Model Context Protocol server that enables Claude Code to perform expect/pexpect-style automation for interactive programs, supporting complex interactions with terminal programs, SSH sessions, databases, and debugging workflows.

  1. ✨ Features
    1. 🖥️ Tmux-Based Terminal Control
    2. 🌐 Optional Web Interface
    3. 🛡️ Comprehensive Security
  2. 🚀 Quick Start
    1. System Requirements
    2. Installation
    3. Configuration
  3. 🔧 Configuration
    1. Configuration File Locations
    2. Configuration Sections
    3. Complete Configuration Example
  4. 🛠️ MCP Tools (5 Tools)
    1. Session Management
    2. Content Retrieval
    3. Input Control
    4. Session Creation
  5. 📚 Usage Examples
    1. Basic Commands
    2. Interactive Programs
    3. Debugging Workflow
    4. Web Interface Usage
  6. 🌐 Web Interface
    1. Real-Time Terminal Access
    2. Session URLs
  7. 🔒 Security
    1. Defense-in-Depth Approach
    2. Agent-Controlled Philosophy
  8. 📁 Project Structure
    1. 🧪 Development
      1. Testing
      2. Code Quality
      3. Development Installation
    2. 🚀 Development Status
      1. 📄 License
        1. 🤝 Contributing
          1. 🙏 Acknowledgments

            Related MCP Servers

            • Calculator MCP Server

              QuantGeekDev
              -
              security
              F
              license
              -
              quality
              A Model Context Protocol server built with mcp-framework that allows users to create and manage custom tools for processing data, integrating with the Claude Desktop via CLI.
              Last updated -
              23
              5
              TypeScript
              • Apple

            • MCP Python Toolbox

              gianlucamazza
              -
              security
              F
              license
              -
              quality
              A Model Context Protocol server that enables AI assistants like Claude to perform Python development tasks through file operations, code analysis, project management, and safe code execution.
              Last updated -
              5
              Python
              • Linux
              • Apple

            • Claude Code MCP

              auchenberg
              A
              security
              A
              license
              A
              quality
              An implementation of Claude Code as a Model Context Protocol server that enables using Claude's software engineering capabilities (code generation, editing, reviewing, and file operations) through the standardized MCP interface.
              Last updated -
              8
              164
              JavaScript
              MIT License

            • my-mcp-server

              15972289829
              A
              security
              F
              license
              A
              quality
              A Model Context Protocol server that allows integration with Claude Desktop by creating and managing custom tools that can be executed through the MCP framework.
              Last updated -
              423
              TypeScript
              • Apple

            View all related MCP servers

            New MCP Servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/wehnsdaefflae/MCPAutomationServer'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server