home / mcp / terminal control mcp server

Terminal Control MCP Server

Provides AI-driven terminal sessions with tmux-backed multiplexing, optional web interface, and secure controls for interactive programs.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "wehnsdaefflae-terminal-control-mcp": {
      "command": "terminal-control-mcp",
      "args": []
    }
  }
}

You can run Terminal Control MCP Server to give AI agents and human users real-time, persistent terminal sessions powered by tmux. It combines secure, multi-user terminal control with an optional web interface for live interaction and supports interactive programs, debuggers, SSH, and database clients in a controlled, auditable environment.

How to use

You interact with the Terminal Control MCP Server through an MCP client. Create or attach to a terminal session to execute commands, view live output, and control timing and interaction in a secure, isolated environment. You can switch between agent-driven control and manual user input via the web interface. Use the session list to find active sessions, attach to a running session, and terminate sessions when finished.

Key workflows you can perform include starting new terminals, sending commands, waiting for specific outputs, and retrieving different views of the terminal content. You can also run interactive programs, like shells, REPLs, or debuggers, with per-session isolation and audit logging to keep activities contained and traceable.

How to install

Prerequisites you need before installing: a supported Python runtime and tmux installed on your system.

Install from PyPI (recommended):

pip install terminal-control-mcp

Install from source (alternative):

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

# Create and activate a virtual environment
python -m venv .venv          # Using standard venv
# OR
uv venv                       # Using uv (faster)

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

# Install the package
pip install .

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

Additional configuration and runtime notes

Configuration supports TOML files and environment variable overrides to tailor behavior for your deployment. You can enable a web interface, set security levels, control session behavior, and adjust terminal parameters.

Example MCP client configuration to add the local server command (stdio) is provided as a reference for clients that manage MCP servers via local processes.

Configuration and security overview

Security is implemented through layered controls including command filtering, path restrictions, rate limiting, history isolation, and audit logs. You can adjust protection levels to off, low, medium, or high to balance usability and safety.

Usage tips for web interface

If you enable the web interface, you get a live xterm.js terminal in your browser with WebSocket updates. You can view all active sessions, open the specific session URL, and interact manually without interrupting agent workflows.

Troubleshooting and notes

Common tips include ensuring tmux is installed, verifying that the server has the required network permissions, and checking that security settings align with your usage needs. When web access is enabled, ensure the web server port is accessible from your client network.

Available tools

list_terminal_sessions

List all active terminal sessions with status information including IDs, commands, states, timestamps, and web URLs if available.

exit_terminal

Terminate and clean up a terminal session, with bidirectional cleanup when agents trigger it or users exit in the web interface.

get_screen_content

Retrieve terminal content in modes such as screen, since_input, history, or tail, with process status included.

send_input

Send raw input to a session, supporting escape sequences. No automatic timeouts; input can be sent in parallel.

await_output

Wait for a regex pattern to appear in terminal output with a configurable timeout and non-blocking polling.

open_terminal

Create a new terminal session with a chosen shell, starting directory, and optional environment.